Captured at (local ISO): 2026-05-18 05:17:14

---

Introduction

While developing in Python, many people run into “SyntaxError: Non-UTF-8 code starting with” or something like “‘utf-8’ codec can’t decode byte 0xb2 in position 0: invalid …”. This often shows up when you add Chinese comments, Chinese identifiers, or process files that contain non-ASCII text. The error looks small, but it touches how encoding works and how your editor interprets bytes. This post starts from the basics, walks through how VS Code picks an encoding when opening a file, explains why the error happens, gives concrete fixes, and covers new errors you might see after “fixing” things the wrong way.

If you care about the theory, read from the top; if you only need a quick fix, jump from the table of contents to the troubleshooting section.

I. What is encoding?

To fix encoding errors, you first need to know what “encoding” means.
In short, encoding is the rule that maps human-readable characters (letters, digits, CJK text, symbols, etc.) to bytes the computer stores; decoding is the reverse.
Over the years many schemes have been used:

ASCII — One of the earliest; only covers English letters, digits, and a small set of symbols (128 code points). It’s English-only and was replaced over time where multilingual text matters.

GB2312 and GBK — Built to display Chinese properly. GB2312 covers ~6,763 commonly used Han characters; GBK extends GB2312 and adds more characters (and is commonly seen as the default on Chinese Windows setups).

UTF-8 — Today’s most widely used encoding on the wire and in tooling. Unicode assigns a unique code point to almost every writing system; UTF-8 is one byte serialization of Unicode. ASCII characters still use one byte; other characters take 2–4 bytes. Most languages, OS defaults, and editors treat UTF-8 as the sane default.

The root issue is simple: if a file was saved using one encoding but read using another, you get garbage or hard decode errors—including “SyntaxError: Non-UTF-8 code starting with” or “‘utf-8’ codec can’t decode byte …”.

II. How your editor selects encoding when opening files (VS Code example)

VS Code follows a predictable pipeline when figuring out “what encoding is this buffer?” Knowing it makes debugging faster.

1. Encoding auto-detection

When VS Code opens a file, it tries to infer encoding in two complementary ways:

• Content-based detection — Inspect raw bytes for signatures and patterns (e.g., UTF‑8 BOM, typical GBK byte ranges when Chinese appears in the payload), then guess encoding.
• Extension + defaults — For file types whose ecosystem strongly prefers UTF‑8 (e.g. .py), VS Code also layers in language defaults and user settings.

2. View and change encoding

Look at the status bar at the bottom right — it shows the current encoding (“UTF‑8”, “GBK”, etc.).

To change it:

• Click that label;
• Use “Reopen with Encoding” to reinterpret bytes with another encoding without rewriting the file, or “Save with Encoding” to transcode and write new bytes;
• Pick from the list (UTF‑8, GB2312, GBK, …).

3. Default encoding settings

Out of the box, new files are UTF‑8. To change the default:

• Open Settings (Ctrl+,);
• Search files.encoding;
• Choose your preferred default (e.g. GBK) from Files: Encoding — new files will save with that encoding afterward.

III. Why the error occurs and how to fix it (“SyntaxError: Non-UTF-8 code starting with”)

1. Cause

Python 3 reads source files as UTF‑8 by default. If the file on disk is not UTF‑8 and contains non‑ASCII characters (Chinese, Japanese, etc.), the interpreter’s UTF‑8 decoder can hit invalid sequences and raise SyntaxError: Non-UTF-8 code starting with ….

Example: you create foo.py in some editor, it ends up saved as GBK, and you write a Chinese comment like # 这是一个测试脚本. Running python foo.py, Python tries UTF‑8; the GBK bytes for that comment aren’t valid UTF‑8 byte sequences → syntax error before your code even runs logically.

2. Fixes

Option 1: Add an encoding cookie at the top of the script (simplest)

This is quick, but you must know the real on-disk encoding. If the file is truly saved as GBK, add at the very top:

# -*- coding: GBK -*-

The name after coding: must match how the file is actually stored (here: GBK).

Option 2: Convert the file to UTF-8 (most reliable)

Transcode the source to UTF‑8 so it matches Python’s default reader.

In VS Code:

1. Open the .py file that errors;
2. Click the encoding label in the status bar (maybe it says “GBK”);
   
3. Choose “Save with Encoding”;
   
4. Pick UTF‑8;
   
5. Remove any old # -*- coding: gbk -*- line or change it to UTF‑8 only if you still need one, then rerun.

Option 3: Replace Chinese in CLI output with English (least recommended)

Renaming prints / tqdm outputs to English can dodge some issues, but it hurts readability for Chinese‑speaking teammates and solves the wrong layer of the problem.

IV. New errors you may hit after fixing and how to handle them

1. Possible follow-up errors

‘utf-8’ codec can’t decode byte 0xb2 in position 0: …
SyntaxError: encoding problem: GBK
UnicodeDecodeError: ‘gbk’ codec can’t decode byte 0xa6 in position xx: illegal multibyte sequence

2. Causes

Usually your cookie doesn’t match the bytes on disk:

• # -*- coding: GBK -*- at the top, but the editor saved UTF‑8;
• Or you transcoded everything to UTF‑8 but forgot to remove the GBK declaration.

Python will then decode with the declared encoding → mismatch explosions.

3. Fixes

Treat it as consistency between three facts: declaration (if any), editor display encoding, bytes on disk.

Step 1: Confirm the file’s actual encoding

Check VS Code’s status bar first. Important: VS Code must reopen the buffer with the encoding that matches the disk bytes; otherwise you’ll “see gibberish” like:

If wrong, reopen with UTF‑8 (or whichever encoding you intend), then Save with Encoding accordingly. For files that aren’t UTF‑8, add the matching # -*- coding: … -*- line if you insist on staying non‑UTF‑8.

You can also detect bytes objectively:

Install chardet from the shell:

pip install chardet

Then run:

import chardet 

# Read raw bytes
with open("your_script_that_errors.py", "rb") as f: 
    data = f.read() 
    result = chardet.detect(data) 
    print("Detection result:", result)

Put the guessed encoding in the # -*- coding: … -*- line only when it truly matches disk.

Step 2: Make the declaration match the file

• If disk is UTF‑8: drop the redundant cookie entirely (Python 3 default), or # -*- coding: utf-8 -*- if policy requires it.
• If disk is GBK: keep # -*- coding: gbk -*- and don’t silently save UTF‑8 on top unless you delete/changed that header at the same time.

Summary

“SyntaxError: Non-UTF-8 code starting with”, later “UnicodeDecodeError”, “SyntaxError: encoding problem…”—all distill to mixed signals about bytes vs encoding: Python’s default UTF‑8 vs real file encoding, or a wrong # -*- coding -*- line.

Flow that works: detect real encoding (status bar; if garbled, reopen correctly; if still unsure, chardet) → one story: UTF‑8 file + no conflicting cookie, or GBK file + matching cookie. That keeps Chinese text without forcing everything into English.