fix: strip UTF-8 BOM from .env files (#640)

* Fix: strip UTF-8 BOM from .env files to prevent silent first-variable loss

When a .env file is saved with a UTF-8 BOM (common with JetBrains IDEs
on Windows), the BOM character (\ufeff) was prepended to the first
variable name, making it silently inaccessible via its intended key.

Strip the BOM in Reader.__init__ so all variables are parsed correctly
regardless of whether the file contains a BOM.

Fixes #637

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add changelog entry for BOM fix

---------

Co-authored-by: h1whelan <h1whelan@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Saurabh Kumar <theskumar@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -7,7 +7,9 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-- ...
+### Fixed
+
+- Strip a leading UTF-8 BOM from `.env` file contents so the first variable is no longer silently lost when the file is saved with BOM (e.g. by some JetBrains IDEs on Windows) by [@h1whelan] in [#640]
 
 ## [1.2.2] - 2026-03-01
 
@@ -432,6 +434,7 @@ os.PathLike]` instead of just `os.PathLike` (#347 by [@bbc2]).
 [#563]: https://github.com/theskumar/python-dotenv/pull/563
 [#497]: https://github.com/theskumar/python-dotenv/pull/497
 [#161]: https://github.com/theskumar/python-dotenv/issues/161
+[#640]: https://github.com/theskumar/python-dotenv/pull/640
 [790c5c0]: https://github.com/theskumar/python-dotenv/commit/790c5c02991100aa1bf41ee5330aca75edc51311
 
 <!-- contributors -->
@@ -460,6 +463,7 @@ os.PathLike]` instead of just `os.PathLike` (#347 by [@bbc2]).
 [@gergelyk]: https://github.com/gergelyk
 [@gongqingkui]: https://github.com/gongqingkui
 [@greyli]: https://github.com/greyli
+[@h1whelan]: https://github.com/h1whelan
 [@harveer07]: https://github.com/harveer07
 [@jadutter]: https://github.com/jadutter
 [@jankislinger]: https://github.com/jankislinger

src/dotenv/parser.py

@@ -68,7 +68,7 @@ class Error(Exception):
 
 class Reader:
     def __init__(self, stream: IO[str]) -> None:
-        self.string = stream.read()
+        self.string = stream.read().removeprefix("\ufeff")
         self.position = Position.start()
         self.mark = Position.start()
 

tests/test_parser.py

@@ -545,6 +545,35 @@
                 ),
             ],
         ),
+        # UTF-8 BOM at the start of the file should be stripped
+        (
+            "\ufeffa=b",
+            [
+                Binding(
+                    key="a",
+                    value="b",
+                    original=Original(string="a=b", line=1),
+                    error=False,
+                )
+            ],
+        ),
+        (
+            "\ufeffa=b\nc=d",
+            [
+                Binding(
+                    key="a",
+                    value="b",
+                    original=Original(string="a=b\n", line=1),
+                    error=False,
+                ),
+                Binding(
+                    key="c",
+                    value="d",
+                    original=Original(string="c=d", line=2),
+                    error=False,
+                ),
+            ],
+        ),
     ],
 )
 def test_parse_stream(test_input, expected):