Skip to content
Velloreth
Technology 5 min read

Config Files vs Environment Variables: Which to Use

A file is versioned and readable; an environment variable is injected and secret. Learn which setting belongs where, and why.

By

The two mechanisms

A config file is a file in the repository, such as config.yaml or appsettings.json. It is versioned, reviewable and structured.

An environment variable is a value injected into the process at runtime. It is not in the repository, and it can differ per environment.

The question is which setting belongs where.

The rule

A setting that is the same everywhere and is not a secret can go in a versioned file.

A setting that differs per environment belongs in the environment.

A secret belongs in an environment variable or a secret store, never in a file.

The test from the twelve-factor app: could the codebase be made open source at any moment without compromising a credential? If not, a secret is in the repository.

What goes in a file

A default that rarely changes. A page size, a retry count, a feature’s default state.

A structured value. A list of routes, a mapping of roles to permissions, a template.

A value that benefits from review. A change to a rate limit should be visible in a diff.

A value that is the same in every environment. A timezone, a locale, a protocol version.

# config/default.yaml
pagination:
  pageSize: 20
  maxPageSize: 100
retry:
  attempts: 3
  backoffMs: 500

What goes in the environment

A connection string. It differs per environment and it contains a credential.

An API key. A secret.

A feature flag that differs per environment. A flag that is on in staging and off in production.

A hostname or a URL. It differs per environment.

A log level. It differs between development and production.

DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=sk_live_...
LOG_LEVEL=info

The hybrid

A file for the defaults, an environment variable for the override.

const config = {
  pageSize: Number(process.env.PAGE_SIZE ?? fileConfig.pagination.pageSize),
  logLevel: process.env.LOG_LEVEL ?? 'info',
};

The advantage: the file documents the shape and the default, and the environment overrides what differs.

The precedence order is worth documenting:

  1. A command-line flag
  2. An environment variable
  3. A file
  4. A built-in default

The more specific source wins. A value that comes from an unexpected source is a common debugging problem, which is why the order is documented.

Secrets

A secret in a file is a secret that can be committed.

The layers of protection:

ApproachProtection
A file in the reponone
A .env file, gitignoredweak, it is on disk
An environment variablemoderate, it is in the process
A secret managerstrong, it is fetched and audited

A secret manager such as Vault, AWS Secrets Manager or a cloud key store fetches the value at runtime, rotates it, and logs the access.

An environment variable is visible to a process listing on some systems, and it appears in a crash dump. It is better than a file and it is not the strongest option.

A secret in git history must be rotated, not just removed. A removal from the current commit does not remove it from the history.

Validation

Validate the configuration at startup.

const schema = z.object({
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().positive(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
});

const config = schema.parse(process.env);

Why: a missing value fails at startup with a clear message, rather than on the first request that needs it.

The failure mode to avoid: a value that is undefined and is used as a string, which produces "undefined" in a URL.

A schema library makes the shape explicit and the error readable.

A default for a non-critical value is fine. A default for a connection string is not.

The .env file

A .env file is a convenience for local development.

# .env.example (committed)
DATABASE_URL=
API_KEY=
LOG_LEVEL=debug

Commit the example, gitignore the real file.

.env
.env.local
.env.*.local

The example documents what is needed, which is the onboarding value.

A .env file that is committed with a real value is a leaked secret.

A .env file in production is a file on disk, which is weaker than an injected variable.

Configuration in a container

A container adds a wrinkle to the configuration question, because the image is built once and run in several environments. The rule is that the image must not contain an environment-specific value, so the configuration is injected at run time. A container platform provides the values as environment variables, and a secret is mounted as a file or injected from a secret store. The second wrinkle is the build: a front-end build that bakes an API URL into the bundle is a build per environment, which breaks the build-once rule. The fix is to read the value at run time from a configuration endpoint or a global injected by the server. The third is the health check: a container that starts with a missing configuration should fail the health check rather than serve errors, which is why the validation at startup matters even more in a container.

Common mistakes

A secret in a committed file. It must be rotated.

A .env file that is committed. The same problem.

No validation. A missing value fails on the first request.

A default for a critical value. A wrong default is worse than a failure.

An undocumented precedence. A value from an unexpected source.

A configuration that requires a code change. The same build should run in every environment.

A boolean parsed as a string. "false" is truthy. Parse it explicitly.

A number parsed as a string. "20" is a string, and a comparison behaves unexpectedly.

A secret in a log. A configuration dump that includes a credential.

A quotable summary

A config file is versioned, reviewable and structured, and an environment variable is injected at runtime and is not in the repository. A setting that is the same everywhere and is not a secret can go in a file, a setting that differs per environment belongs in the environment, and a secret belongs in an environment variable or a secret store. Use a file for the defaults and an environment variable for the override, document the precedence, and validate the configuration at startup so a missing value fails fast.

For the related topics, see environment-variables-best-practices and secret-management-guide. For the broader context, twelve-factor-app-explained and json-vs-yaml-vs-toml.

Frequently asked questions

Should configuration go in a file or an environment variable?
A setting that is the same everywhere and is not a secret can go in a versioned file, because it is reviewable and structured. A setting that differs per environment, or that is a secret, belongs in an environment variable or a secret store. A common pattern is a file for the defaults and an environment variable for the override.
Why are environment variables preferred for secrets?
Because they are injected at runtime and are not in the repository, so a secret is not committed. A file with a secret is a file that can be committed by accident, and a secret in git history is a secret that must be rotated. An environment variable is not a perfect store either, and a secret manager is better for a production system.
What is the twelve-factor approach to configuration?
It says to store the configuration in the environment, so the same build can run in any environment without a code change. The test is whether the codebase could be made open source at any moment without compromising a credential. A config file that is committed and contains a secret fails that test.
What is the precedence order for configuration?
The common order is: a command-line flag, then an environment variable, then a file, then a built-in default. The more specific source wins. Document the order, because a value that comes from an unexpected source is a common debugging problem.
How do I validate configuration?
Parse and validate every value at startup, and fail with a clear message if one is missing or malformed. A schema library makes this explicit. Failing at startup is much better than failing on the first request that needs the value.
Should I commit a .env file?
Commit a .env.example with the keys and no values, and add .env to .gitignore. The example documents what is needed, and the real file is not committed. A .env file that is committed with a real value is a leaked secret.