Do i need to update .env every time?

[peterrookie]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

Best Practice for updating .env files during version upgrades?

Hi team and community,

I have a question regarding the best practices for upgrading Dify versions, specifically around the .env file management.

Current Approach:
Whenever a new Dify version is released, I manually compare my current .env file with the latest .env.example (or the new .env). I then manually port over any new configuration keys while preserving my custom parameter values.

My Questions:

1. Is it strictly necessary to update/sync the .env file for every single release?
2. I noticed that the official Release Notes rarely mention whether .env changes are required for that specific version. Should I continue with my manual comparison approach, or is there a standard/recommended way to handle this during upgrades?

Any advice or insights on how you manage this efficiently would be greatly appreciated! Thanks!

[dosubot[bot]]

Great question! Here's the short answer:

Yes, you should update your .env file when upgrading, but you don't need to do it manually. Dify provides a built-in sync script for this [1]:

cd docker
chmod +x dify-env-sync.sh
./dify-env-sync.sh

This script automatically [2]:

• Creates a timestamped backup of your current .env
• Adds any new variables from .env.example
• Preserves all your existing custom values (it never overwrites them)
• Reports removed/renamed variables for your manual review

So it does exactly what you've been doing manually, but safely and automatically.

Regarding whether every release requires .env changes — not every release introduces new env vars, but some do (and the release notes don't always call this out explicitly). The safest habit is to run dify-env-sync.sh after every upgrade. If nothing changed, the script simply does nothing.

One important example: the v1.12.x upgrade renamed the PostgreSQL container hostname from db to db_postgres and changed several DB_* variable names — skipping the .env update in that case causes immediate connection failures [3].

The recommended upgrade sequence is documented in docker/README.md:

1. Back up your database, volumes, and .env
2. docker compose down
3. Pull the new version
4. Run ./dify-env-sync.sh
5. docker compose up -d

Also worth noting: incremental upgrades (e.g., 1.11 → 1.12 → 1.13) are recommended over large version jumps [3].

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.