Dotenv (.env Configuration Files)

Dotenv (.env) is a standardized plain-text configuration convention engineered to separate application code from environment-specific configuration parameters, secrets, and credentials. Popularized by the Twelve-Factor App methodology (Factor III: Config), Dotenv enables developers to define key-value pairs in local .env files that application runtimes automatically load into system environment variables (process.env in Node.js, os.environ in Python, or std::env in Rust).

Parse, validate, and convert .env files into JSON, YAML, Docker, or Kubernetes ConfigMaps using our free Env File Parser & Converter or convert JSON objects to .env format with JSON to .env.

---

Technical Specifications at a Glance

Specification	Details
Standard Filename	.env, .env.local, .env.development, .env.production
File Format / Grammar	Plain-text key-value pairs (KEY=value), line-delimited
Comment Syntax	# (leading character or after unquoted whitespace)
Character Encoding	Strict UTF-8
Quoting Support	Bare (unquoted), single quotes ('...'), double quotes ("...")
Primary Ecosystems	Node.js (dotenv, dotenvx), Next.js, Vite, Python (python-dotenv), Ruby, Go, Docker, Kubernetes
Security Rule	Always add .env / .env.local to .gitignore to prevent credential leaks

---

Dotenv Syntax & Quoting Rules

# Basic Primitive Types
PORT=3004
NODE_ENV=production
DEBUG=false

# 1. Bare (Unquoted): Suitable for simple primitives and strings without whitespace
DATABASE_HOST=db.internal.wtool.dev

# 2. Single Quotes (' '): Preserves literal values without escape evaluation or variable interpolation
SPECIAL_REGEX='^[a-z0-9_-]+$'
RAW_STRING='Value with $dollar and \n literal escapes'

# 3. Double Quotes (" "): Evaluates escape characters (\n, \t) and parameter expansions
WELCOME_MESSAGE="Hello,\nWelcome to DevFlow!"
API_BASE_URL="https://${DATABASE_HOST}/api/v1"

# 4. Multiline Values (RSA Private Keys & Certificates)
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA0Yq3...
-----END RSA PRIVATE KEY-----"

# 5. Shell Export Prefix (Optional for Unix sourcing)
export CACHE_DRIVER=redis

Quoting Rules Comparison

Quoting Style	Escape Sequences (\n, \t)	Variable Expansion (${VAR})	Preserves Inner Quotes	Use Cases
Unquoted (KEY=val)	Ignored (literal \n)	Supported in some parsers	Requires backslash escaping	Integers, booleans, simple URLs
Single Quotes (KEY='val')	Ignored (strictly literal)	Ignored (literal ${VAR})	Cannot contain single quotes	RegEx patterns, raw strings
Double Quotes (KEY="val")	Evaluated (\n → newline)	Evaluated (expands ${VAR})	Can escape inner quotes \"	Multiline secrets, certificates, templates

---

Environment Precedence in Modern Frameworks

Modern frameworks (such as Next.js, Vite, Remix, and Nuxt) load configuration files using a strict cascading priority hierarchy:

[Highest Priority]
1. Process Environment (process.env injected via OS, Docker, or CI/CD)
2. .env.${NODE_ENV}.local (e.g., .env.production.local or .env.development.local)
3. .env.local (Local machine overrides; gitignored)
4. .env.${NODE_ENV} (Environment-specific defaults, e.g., .env.production)
5. .env (Base project defaults; checked into Git)
[Lowest Priority]

---

Code Examples: Loading Dotenv Across Environments

Node.js & TypeScript (dotenv / dotenvx)

import 'dotenv/config';

// Accessing loaded environment variables
const port = parseInt(process.env.PORT || '3000', 10);
const dbUrl = process.env.DATABASE_URL;

if (!dbUrl) {
  throw new Error('DATABASE_URL is required in environment configuration');
}

console.log(`Server starting on port ${port}`);

Python 3 (python-dotenv)

import os
from dotenv import load_dotenv

# Load variables from .env file into environment
load_dotenv()

database_host = os.getenv("DATABASE_HOST", "localhost")
api_key = os.environ["API_KEY"]

Docker & Container Execution

# Inject .env file into Docker container at runtime
docker run --env-file .env -p 3004:3004 my-app:latest

---

Frequently Asked Questions

Why should .env files never be committed to Git?

.env files frequently contain sensitive database credentials, API secret keys, OAuth client secrets, and encryption keys. Committing them to version control exposes credentials to everyone with repository access and public crawlers. Commit a sanitized .env.example file instead and keep actual .env files listed in .gitignore.

What is the difference between .env and .env.example?

.env contains active credentials and private configuration for the running application instance. .env.example is a sanitized, non-secret template committed to version control that documents every required environment variable and expected format for onboarding developers.

How do I convert .env files into Kubernetes ConfigMaps?

You can convert key-value pairs into a Kubernetes ConfigMap YAML manifest (apiVersion: v1, kind: ConfigMap) with our Env File Parser & Converter or convert nested structures with our JSON to .env tool.