●Change8

Migrating to python-dotenv v1.2.2

Version v1.2.2 introduces 3 breaking changes. This guide details how to update your code.

Released: 3/1/2026

3
Breaking Changes
2
Migration Steps
3
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

dotenv.set_keydotenv.unset_keydotenv run (CLI)

Breaking Changes

●Issue #1

The behavior of `dotenv.set_key` and `dotenv.unset_key` regarding symlinks has changed; they no longer follow symlinks by default. To restore the previous behavior of following symlinks, use `follow_symlinks=True`.

●Issue #2

The CLI commands `set` and `unset` no longer follow symlinks in some situations where they previously did.

●Issue #3

The file mode of modified .env files is no longer unconditionally reset to `0o600` by `dotenv.set_key`, `dotenv.unset_key`, or the CLI commands `set`/`unset`. The original file mode is now preserved, unless the file is being created or is not a regular file, in which case mode `0o600` is used.

Migration Steps

  1. 1
    If you relied on `dotenv.set_key` or `dotenv.unset_key` following symlinks, update calls to include `follow_symlinks=True`.
  2. 2
    Review usage of `dotenv run` to ensure flag forwarding behavior is as expected.

Release Summary

This release introduces support for Python 3.14 and updates the behavior of key setting/unsetting functions regarding symlinks and file modes, resulting in breaking changes for symlink following and file mode preservation.

Need More Details?

View the full release notes and all changes for python-dotenv v1.2.2.

View Full Changelog