Field Notes

Be explicit about text encoding in Python

August 14, 2025

A small script of mine read a text file and printed it. On my Linux server it was fine; on a colleague's Windows laptop the same file came out as garbage. The file had not changed. The default had.

The cause

When you call open() in text mode without an encoding argument, Python picks a default based on the operating system's locale. On many Linux systems that is UTF-8, on Windows it can be a legacy code page. The same bytes are then decoded differently.

The fix

with open("notes.txt", encoding="utf-8") as f:
    text = f.read()

with open("out.txt", "w", encoding="utf-8", newline="\n") as f:
    f.write(text)

Say what you mean every time you read or write text. Passing newline="\n" when writing keeps line endings the same on every platform, which also keeps diffs clean.

For quick scripts

If you cannot edit the code, setting the environment variable PYTHONUTF8=1 turns on Python's UTF-8 mode for that run. It is a good stopgap, but being explicit in the code is the version that keeps working when somebody runs it somewhere else.

← All notes