fix: preserve a leading BOM when set_key and unset_key rewrite a file

CHANGELOG.md

@@ -10,6 +10,7 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### Fixed
 
 - An unquoted empty value followed by an inline comment (e.g. `KEY= # comment`) is now parsed as an empty string instead of the comment text by [@Noethix55555] in [#663]
+- A leading UTF-8 BOM is now preserved when `set_key` or `unset_key` rewrites a `.env` file, instead of being silently dropped by [@MohammedAlkindi] in [#687]
 
 ## [1.2.3] - 2026-08-16
 
@@ -448,6 +449,7 @@ os.PathLike]` instead of just `os.PathLike` (#347 by [@bbc2]).
 [#640]: https://github.com/theskumar/python-dotenv/pull/640
 [#663]: https://github.com/theskumar/python-dotenv/pull/663
 [#680]: https://github.com/theskumar/python-dotenv/pull/680
+[#687]: https://github.com/theskumar/python-dotenv/pull/687
 [790c5c0]: https://github.com/theskumar/python-dotenv/commit/790c5c02991100aa1bf41ee5330aca75edc51311
 
 <!-- contributors -->
@@ -487,6 +489,7 @@ os.PathLike]` instead of just `os.PathLike` (#347 by [@bbc2]).
 [@lsmith77]: https://github.com/lsmith77
 [@matthewfranglen]: https://github.com/matthewfranglen
 [@mgorny]: https://github.com/mgorny
+[@MohammedAlkindi]: https://github.com/MohammedAlkindi
 [@naorlivne]: https://github.com/naorlivne
 [@Noethix55555]: https://github.com/Noethix55555
 [@qnighy]: https://github.com/qnighy

src/dotenv/main.py

@@ -172,6 +172,14 @@ def rewrite(
 
         try:
             with source:
+                # The parser strips a leading BOM, so it never reaches the
+                # bindings the caller writes out.  Carry it across here, or
+                # rewriting a file that has one silently drops it.
+                if source.seekable():
+                    if source.read(1) == "\ufeff":
+                        dest.write("\ufeff")
+                    else:
+                        source.seek(0)
                 yield (source, dest)
         except BaseException as err:
             error = err

tests/test_main.py

@@ -106,6 +106,17 @@ def test_set_key_preserves_file_mode(dotenv_path):
     assert mode_before == mode_after
 
 
+def test_set_key_preserves_byte_order_mark(dotenv_path):
+    dotenv_path.write_bytes(b"\xef\xbb\xbfa=x\n")
+
+    dotenv.set_key(dotenv_path, "b", "y")
+
+    contents = dotenv_path.read_bytes()
+    assert contents.startswith(b"\xef\xbb\xbf")
+    assert contents.count(b"\xef\xbb\xbf") == 1
+    assert dotenv.dotenv_values(dotenv_path) == {"a": "x", "b": "y"}
+
+
 def test_rewrite_closes_file_handle_on_lstat_failure(tmp_path):
     dotenv_path = tmp_path / ".env"
     dotenv_path.write_text("a=x\n")
@@ -303,6 +314,17 @@ def test_unset_encoding(dotenv_path):
     assert dotenv_path.read_text(encoding=encoding) == ""
 
 
+def test_unset_preserves_byte_order_mark(dotenv_path):
+    dotenv_path.write_bytes(b"\xef\xbb\xbfa=x\nb=y\n")
+
+    result = dotenv.unset_key(dotenv_path, "b")
+
+    assert result == (True, "b")
+    contents = dotenv_path.read_bytes()
+    assert contents.startswith(b"\xef\xbb\xbf")
+    assert dotenv.dotenv_values(dotenv_path) == {"a": "x"}
+
+
 def test_unset_non_existent_file(tmp_path):
     nx_path = tmp_path / "nx"
     logger = logging.getLogger("dotenv.main")