Introduction

Writing UTF-8 text in Python is simple once you make the encoding explicit. The safest habit is to open text files with encoding="utf-8" so the file contents do not depend on the operating system’s default encoding.

Basic UTF-8 Writing with open

The standard approach is to open the file in text mode and pass the encoding you want.

1text = "Hello, world.
2"
3text += "Café
4"
5text += "こんにちは
6"
7text += "🙂
8"
9
10with open("output.txt", "w", encoding="utf-8") as file:
11    file.write(text)

This writes Unicode text correctly as UTF-8 bytes on disk. The with block is important because it closes the file cleanly even if an error occurs.

Appending Instead of Replacing

Use append mode when you want to add more UTF-8 text without replacing the existing file.

with open("output.txt", "a", encoding="utf-8") as file:
    file.write("Another line in UTF-8
")

The encoding parameter still matters. Opening in append mode without it can work on one machine and fail on another if the platform default differs.

pathlib Can Be Even Cleaner

If you prefer modern path handling, pathlib.Path provides a convenient write_text method.

1from pathlib import Path
2
3path = Path("report.txt")
4path.write_text("Résumé
5naïve
6España
7", encoding="utf-8")

This is especially nice in small scripts where you do not need manual control over the file handle.

Newlines and Cross-Platform Files

Python text mode handles newline translation for you. In most cases that is fine. If you need exact newline behavior, pass newline=" " explicitly.

1with open("unix_style.txt", "w", encoding="utf-8", newline="
2") as file:
3    file.write("line one
4line two
5")

That can matter when a downstream tool expects a specific line ending style.

Writing Structured Data

When writing JSON, remember that UTF-8 file encoding and JSON escaping are separate concerns. If you want readable non-ASCII characters in the file, set ensure_ascii=False.

1import json
2
3payload = {
4    "city": "Montréal",
5    "greeting": "你好",
6}
7
8with open("data.json", "w", encoding="utf-8") as file:
9    json.dump(payload, file, ensure_ascii=False, indent=2)

Without ensure_ascii=False, Python still writes a valid file, but many non-ASCII characters appear as escape sequences instead of readable text.

Reading Back for Verification

If encoding problems matter in your workflow, verify by reading the file back with the same encoding.

with open("output.txt", "r", encoding="utf-8") as file:
    print(file.read())

This is a good sanity check when text comes from multiple languages or external systems.

When You Need Error Handling

Most text pipelines should fail loudly if invalid data reaches the write step, which is why the default error handling is usually correct. If you are dealing with messy upstream text, Python also lets you pass an errors strategy such as replace or ignore, but that should be a deliberate tradeoff because it can hide data-quality problems.

with open("cleaned.txt", "w", encoding="utf-8", errors="replace") as file:
    file.write("Bad data will be replaced if needed.")

Common Pitfalls

• Omitting the encoding argument makes behavior depend on the system default encoding.
• Writing bytes to a text file or strings to a binary file causes type errors.
• Forgetting ensure_ascii=False in JSON can make the file harder for humans to read.
• Mixing encodings between write and read operations produces decode errors or mojibake.
• Opening the file with mode "w" when you meant "a" will replace the previous contents.

Summary

• Use encoding="utf-8" whenever you write text files in Python.
• Prefer with open(...) for safe file handling.
• 'pathlib.Path.write_text is a clean alternative for simple cases.'
• Control newlines explicitly only when another tool requires it.
• For JSON, combine UTF-8 output with ensure_ascii=False when readable Unicode matters.