VPS Tutorials
Docker Compose ignores .env changes: precedence, recreation and app settings
Separate Compose interpolation, container environment and application settings; find overrides, recreate the right service and verify persistence without exposing secrets.

You edited .env, restarted the container and still see the old API key, database address or mode. Check two things first: whether the file contributes to this service's configuration, and whether the container was recreated with that configuration.
.env, the CLI option --env-file and the service field env_file have different roles. Follow Compose interpolation → container creation → application configuration. The example service is app; substitute your actual name. Diagnostics use harmless variables so you do not need to print real credentials.
| Symptom | Check first | Next step |
|---|---|---|
| variable is not set warning | Missing interpolation file or misspelled name | Select the file explicitly and inspect ${VAR} |
| Expanded config already has the old value | Shell variable, hard-coded value or override file | Identify the overriding source |
| Config is new, container is old | Only restarted, or selected another project | Confirm project and recreate the target service |
| Container is new, page is unchanged | Application cache or build-time variable | Update application settings or rebuild as documented |
| Database authentication fails after changing a password variable | Initialization variable and existing account differ | Use the database's credential-rotation procedure |
Docker's restart reference states that restart does not apply changed environment variables to an existing container. Inspect the configuration before choosing recreation.
Suppose the project contains .env:
APP_MODE=production
The variable affects a field when the Compose file references it:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
environment:
APP_MODE: "${APP_MODE:?请设置 APP_MODE}"
This is a diagnostic example with no business data or published ports. The Alpine image is only for observing configuration; do not replace your application image with it.
Use CLI --env-file /实际路径/.env.production if the interpolation file is elsewhere. Merely creating .env does not inject all its variables into every container. See interpolation and lookup rules.
Alternatively, reference a file at service level:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
env_file:
- ./app.env
Putting APP_MODE=production in app.env supplies it to the app container. Relative paths are based on the Compose file location, not necessarily the directory of your shell command. See service environment configuration.
A separate field containing ${APP_MODE} does not obtain interpolation values merely because the service has env_file. Project interpolation and container environment injection are separate steps.
Enter the real deployment directory. Here the examples use /opt/myapp, compose.yaml and .env.production:
cd /opt/myapp
pwd
ls -la compose.yaml .env.production
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production config --quiet
Replace all paths. config --quiet checks parsing without printing the entire expanded configuration. To inspect one harmless variable, use config without --quiet in your private terminal and locate its service. Expanded output may contain passwords and connection strings; redact it before sharing.
If deployment uses multiple -f options, a fixed -p project name or another --project-directory, preserve them in diagnostics. Changing -p casually can create another set of containers. Panels such as 1Panel or Portainer may store separate environment or Stack settings; editing a host file does not update that source automatically.
Check for an identically named variable in the current shell. Shell variables take precedence during interpolation; --env-file does not override every source. In a test-only project:
APP_MODE=from-shell docker compose --env-file .env config
Even if .env contains APP_MODE=production, the example ${APP_MODE} resolves to from-shell. If the production command should not inherit that shell variable, verify its name and scope before using unset APP_MODE in the current session and checking again.
At service level, environment overrides env_file:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
env_file:
- ./app.env
environment:
APP_MODE: development
Changing APP_MODE in app.env will not replace the explicit value in environment. An explicitly empty value can also override the file; inspect keys as well as old strings. See environment precedence.
Additional Compose files can override a service too. config is useful only when its options match the actual deployment invocation.
Verify configuration, persistent mounts and rollback first, then use a maintenance window. These commands retain the same file options and target only app:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production up -d --no-deps app
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production ps app
Docker's up reference explains that up recreates affected containers when configuration changes, retaining mounted volumes. A single-instance service briefly stops. Data in an unmounted container writable layer is not persistent data. --no-deps is suitable when dependencies already work and only the application needs updating; coordinate dependency changes separately.
If the model is correct and explicit recreation is necessary:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production up -d --no-deps --force-recreate app
Forced recreation does not fix precedence or automatically rebuild the image. You need not run down first. Do not use down -v or delete volumes as an environment-variable repair.
For a harmless example variable, an image containing printenv can run:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production exec app printenv APP_MODE
Minimal images may not include that executable; use the application's diagnostic interface instead. Do not dump all variables to confirm a key change. Then test a real business request: running status alone does not prove the application adopted the setting.
For dollar signs, check interpolation and quoting. Single-quoted values in Compose's .env are literal. Bash syntax is not universal env-file syntax, and docker run --env-file behaves differently from Compose. Verify with a harmless DEMO_VALUE before real secrets.
Some versions serialize an escaped $$ in config output. That alone does not prove the container receives two dollar signs.
To defer a variable to the container's shell, use $$ in Compose:
services:
app:
image: alpine:3.22
environment:
APP_MODE: production
command: ["sh", "-c", "printf '%s\\n' \"$$APP_MODE\"; sleep 3600"]
The interpolation specification explains how $$ prevents early substitution. This example invokes sh -c explicitly. An array-form command does not itself provide shell expansion, and the image must contain the selected shell.
Investigate application settings next. Laravel can cache configuration; frontend variables may be embedded during a build; other services store settings in the database after initialization. Follow the application's cache, build and storage procedures instead of repeatedly recreating containers.
A database initialization password is not an interface for rotating an existing account's password. With an existing data volume, change the account through the database's supported procedure and then synchronize application credentials. Preserve backups and rollback access; deleting the volume to rerun initialization destroys data.
Completion means config resolves correctly with the same deployment options, the intended container adopts the setting, a business request succeeds and persistent data and dependencies remain healthy.
The original article reports parsing four YAML examples with Docker Compose 2.17.3, checking shell precedence, rejection of an empty required value and serialization of a literal dollar sign. The default was production, shell override from-shell, and explicit environment override development. That validation had no running Docker daemon: it did not recreate containers or validate a production VPS workload.
For related work: