ENV Variable Naming Conventions & Best Practices

Environment variables are a shared language across services, platforms, and teams. Clear, consistent naming keeps configs portable, avoids collisions, and prevents painful “it works locally” bugs. This guide gives you pragmatic naming rules you can adopt as a team standard, plus examples and pitfalls to avoid.

If you follow the 12-factor “Config” principle, sane naming is what makes that portability real across languages, shells, and CI/CD runners.

Why naming conventions matter

ENV variables are often global and reused across services; sloppy naming causes collisions and misreads.
Consistency improves readability for humans and for automation (CI/CD, scripts, secret stores).
Portability depends on sticking to character sets that shells and containers handle reliably.

Recommended conventions

Use UPPERCASE + underscores

Stick to SCREAMING_SNAKE_CASE: DB_HOST, API_KEY, REDIS_URL. It stands out from code variables and aligns with OS and shell conventions.

Only letters, digits, and underscore

Avoid dots, dashes, and spaces. Portable keys look like PAYMENTS_WEBHOOK_SECRET, not payments.webhook-secret.

Meaningful, descriptive names

Be explicit: MAILER_SMTP_HOST beats SMTP1. Add prefixes when multiple services coexist: ANALYTICS_API_KEY, BILLING_DB_HOST.

Namespace third-party or shared packages

If you publish packages or shared tooling that require env vars, prefix them with a vendor or package name to avoid collisions (ACME_FEATURE_FLAG_KEY, ACME_SEARCH_ENDPOINT). Document these expectations so host apps know what to set.

Keep names consistent across environments

The key stays the same in dev, staging, and production; only the value changes. This avoids deploy-time mistakes and config drift and pairs well with the Laravel multi-environment secrets strategy outlined in our companion guide.

Start with a letter or underscore

Some platforms misbehave with digit-starting names. Keep it simple: APP_ENV not 1ST_APP_ENV.

Document purpose and format

Use .env.example, README, or secret-store metadata to describe what each key does, valid formats, and whether it is sensitive. Tools like Ghostable keep that metadata in sync with the actual secrets your team manages.

Common pitfalls

Mixing styles (db_host, DATABASE_HOST, DbHost) and causing confusion.
Using dashes, dots, or spaces that break on some shells or make logs ambiguous.
Encoding environment names into keys (PROD_DB_HOST vs DEV_DB_HOST) instead of keeping one key and varying values.
Skipping documentation, leaving teammates guessing or copying secrets around.

Suggested team standard

All env keys are UPPERCASE.
Words separated by underscores only.
Allowed characters: A-Z, 0-9, underscore; nothing else.
Names are descriptive and prefixed when needed (SERVICE_DB_HOST, PAYMENT_GATEWAY_API_KEY).
Key names are identical across environments; values differ by environment.
Do not start names with digits.
Document every key: purpose, format, sensitivity, environment usage.
Maintain a central reference (.env.example, docs, or secret-store metadata).

Good vs. bad examples

Good	Bad	Notes
`APP_ENV`	`app-env`	Avoid dashes; use underscores.
`DATABASE_URL`	`database.url`	Dots can break in shells and tooling.
`PAYMENTS_WEBHOOK_SECRET`	`WEBHOOK1`	Be descriptive; avoid opaque names.
`BILLING_DB_HOST`	`PROD_DB_HOST`	Prefix by service, not environment.
`ANALYTICS_API_KEY`	`123APIKEY`	Do not start with digits.

How this works with Ghostable

Consistent keys: A single naming standard keeps secrets aligned across services and environments.
Collision avoidance: Prefixing and descriptive names prevent accidental overwrites in shared stores.
Documentation: Pair .env.example with Ghostable metadata so teammates know purpose, format, and sensitivity.
Cross-stack portability: Uppercase + underscores works for PHP, Node, Python, Ruby, and CI/CD tooling alike.

Conclusion

Pick a clear naming convention, enforce it, and document it. Uppercase, underscores, descriptive prefixes, and consistent keys across environments will make your configs portable, safer, and easier to automate—whether you are shipping Laravel, Node, or mixed stacks. For a concrete template of how to document keys, see our Laravel .env.example guide.

FAQ

Stick with uppercase and underscores. It is the most portable and avoids surprises in shells, Docker, and CI systems.

Avoid them. Use only letters, digits, and underscores to prevent parsing issues across platforms.

Keep key names identical across environments; change only the values. This prevents drift and reduces deploy-time mistakes.

Use clear prefixes/namespaces (e.g., BILLING_DB_HOST, ANALYTICS_API_KEY) so different services remain distinct.

Use a committed template like .env.example plus README or secret-store metadata describing purpose, format, and sensitivity.