On the issue of modifying environment variables

[maomao-paradox]

Ask a Question!

I directly modified the environment variables of a certain stack in the portainer_data directory on the server, for example, /var/lib/docker/volumes/portainer_data/_data/compose/1/stack.env. However, when I checked in the Portainer UI, I found that the environment variables did not take effect. Why is this?

[Nick-Portainer]

Hi @maomao-paradox here is a full breakdown on why this is happening.

Why Directly Editing stack.env Has No Effect in the Portainer UI

Two Sources of Truth

Portainer maintains two separate stores for stack environment variables, and they do not automatically sync with each other:

Store	Location	What it controls
Portainer Database (portainer.db)	/var/lib/docker/volumes/portainer_data/_data/portainer.db	What the Portainer UI displays and what is used on the next deploy
stack.env file on disk	/var/lib/docker/volumes/portainer_data/_data/compose/<id>/stack.env	Used by docker compose at runtime

How stack.env Is Actually Generated

The stack.env file is not the source of truth. It is a generated artifact. Every time a stack is deployed or updated, Portainer:

1. Reads the env vars from its internal database (stack.Env field stored in portainer.db)
2. Overwrites stack.env on disk with those values (using O_TRUNC, which clears the file before writing)

This means any manual edits to stack.env will be silently overwritten the next time Portainer touches the stack.

Why the Portainer UI Does Not Reflect Your Change

The UI reads env vars from the database via the API, not from the file on disk. Since only the file was modified and not the database record, the UI continues to show the original values.

The Correct Way to Update Environment Variables

Always use the Portainer UI or API:

• Via UI: Go to Stacks, select your stack, open the Editor tab, update the environment variables, and click Update the stack.
• Via API: PUT /api/stacks/<id>?endpointId=<id> with the updated Env array in the request body.

This updates the database record, regenerates stack.env from the new values, and redeploys the stack correctly.

Note for Repository-based Stacks

For Git-based stacks, Portainer does not auto-generate stack.env from the database. The file must already exist in the Git repository. Environment variables set in the Portainer UI for repository stacks are passed as substitution variables, not written to a stack.env file.

[maomao-paradox]

Thank you for your reply, it has been very helpful to me.  Actually, I encountered this issue during the backup migration of Portainer. Since the IP address of the migrated machine is different, I need to make extensive modifications to the IP-related configurations in the environment variables, which is quite troublesome. That’s why I thought of using a script to directly modify the files stored on the disk in batches. I am now attempting to make batch modifications via the API and hope it will be successful. I would be very grateful if you have any better suggestions for my specific issue.