ImportError: bad magic number (tested)

ImportError: bad magic number in 'mod': b'...' means Python tried to load a .pyc file it can't use. We measured the three situations behind it on Python 3.13.5.

1. What the magic number is

import importlib.util, os, py_compile, sys
os.makedirs("pkg", exist_ok=True)
open("pkg/mod.py", "w").write("X = 1\n")
pyc = py_compile.compile("pkg/mod.py", cfile="pkg/mod.pyc")
os.remove("pkg/mod.py")                       # only the .pyc is left (shipped or stale)
data = bytearray(open(pyc, "rb").read())
data[0:2] = (3000).to_bytes(2, "little")      # pretend another Python version wrote it
open(pyc, "wb").write(data)
sys.path.insert(0, "pkg")
try:
    import mod
except ImportError as e:
    print("ImportError:", e)
print("this Python's magic:", importlib.util.MAGIC_NUMBER)

Output:

ImportError: bad magic number in 'mod': b'\xb8\x0b\r\n'
this Python's magic: b'\xf3\r\r\n'

Every .pyc file starts with a 4-byte magic number that identifies the Python version that compiled it. Measured on Python 3.13.5: a .pyc written with a different magic, and with no .py source next to it, fails with ImportError: bad magic number in 'mod' and shows the bytes it found. Bytecode is not portable across minor versions, so a .pyc-only package built for 3.11 won't import on 3.13. Fix: get the .py source, or rebuild the .pyc with the Python you run (python3 -m compileall).

2. A file that isn't bytecode at all

import os, sys
os.makedirs("pkg2", exist_ok=True)
open("pkg2/notes.pyc", "w").write("these are not bytecode\n")   # a text file named .pyc
sys.path.insert(0, "pkg2")
try:
    import notes
except ImportError as e:
    print("ImportError:", e)

Output:

ImportError: bad magic number in 'notes': b'thes'

Measured: the "magic" shown is just the first 4 bytes of the file, here b'thes' from a text file. If the bytes look like text, HTML (b'<!DO') or zeros, the file is a misnamed file or a broken download (for example an HTML error page saved as .pyc), not a version mismatch.

3. Stale __pycache__ files are not the problem

import os, sys
os.makedirs("pkg3/__pycache__", exist_ok=True)
open("pkg3/mod3.py", "w").write("X = 'from source'\n")
# a bad cache file next to the source is ignored and rewritten, not an error
open(f"pkg3/__pycache__/mod3.{sys.implementation.cache_tag}.pyc", "wb").write(b"\x00" * 16)
sys.path.insert(0, "pkg3")
import mod3
print(mod3.X)

Output:

from source

Measured: a garbage file in __pycache__ next to a real .py is ignored: the import used the source and rewrote the cache file (we checked: it went from 16 bytes of zeros to a valid file). So if you see this error, look for a .pyc sitting outside __pycache__, which Python loads only when there is no .py beside it. Deleting stray *.pyc files (find . -name "*.pyc" -not -path "*/__pycache__/*") is the usual fix.

Frequently asked questions

What does ImportError: bad magic number mean?

Python found a .pyc file whose first 4 bytes don't match its own bytecode version. We measured it with a .pyc from a different magic and no .py source, on Python 3.13.5.

How do I fix bad magic number in Python?

Delete the stray .pyc (one outside __pycache__) so Python uses the .py source, or recompile with your Python via python3 -m compileall. If the bytes shown look like text, the file isn't bytecode at all.

Does a stale __pycache__ cause bad magic number?

Not when the .py source exists: we measured a garbage cache file being ignored and rewritten. The error comes from .pyc files loaded without source.

Can I run a .pyc from another Python version?

No, bytecode differs between minor versions; the magic number check rejects it.

Written with AI assistance. Measured on 2026-10-09 with Python 3.13.5 on Linux: a sourceless .pyc with a different magic number, a text file named .pyc, and a garbage __pycache__ entry next to real source (and its rewritten size). Every block was run verbatim and its output pasted from that run. PlainHeaders is our extension; everything else here is built-in Python.