What Is Magic Number? Definition & Examples

A magic number is the version marker embedded in a compiled Python file to show which interpreter produced it. If the runtime version does not match, import can fail with a bad magic number error. This is both a compatibility constraint and a useful integrity signal during analysis.

Version marker and interpreter compatibility

In Python, the magic number is the compact version marker embedded in compiled .pyc files. It tells the runtime which interpreter produced the bytecode, so import machinery can reject incompatible cache files before execution begins.

That compatibility check matters because bytecode is not meant to be portable across arbitrary interpreter versions. When the marker does not match, the loader treats the file as stale or invalid rather than attempting to run code that may have different opcodes or layout expectations.

For developers and build systems, this makes the magic number part of the Python execution contract, not just an internal header. If environments are mixed, or caches are copied between machines and versions, the marker becomes the first line of defense against subtle import-time failures.

How the import system uses it

The magic number is read during import when Python evaluates a compiled file as a cache for source. If the file header matches the running interpreter, the loader can trust that the bytecode format is recognizable and proceed with deserialization and execution.

If it does not match, import fails with a bad magic number error, which is a deliberate safety condition. That failure prevents a newer or older interpreter from misreading bytecode that was built for a different runtime implementation.

Because the marker is tied to the interpreter build, it also helps distinguish genuine bytecode from unrelated files that happen to have the same extension. In practice, it is one of the basic integrity checks that keeps Python’s import path from treating arbitrary data as executable bytecode.

Why the marker matters in build and deployment workflows

Magic number mismatches often show up when teams deploy precompiled Python artifacts across different versions, rebuild environments without clearing caches, or ship containers whose runtime does not match the build stage. The problem is usually not the code itself, but a mismatch between the cached bytecode and the active interpreter.

That is why compiled artifacts should be treated as environment-specific outputs. A clean build on the target interpreter is safer than assuming cache files remain valid across patch levels, minor versions, or distribution variants.

The operational lesson is simple: when a bad magic number error appears, look first at version drift, stale bytecode, or misplaced cache files. Those are the usual causes, and they are more common than file corruption.

Analysis and integrity signals

Although the magic number exists for compatibility, it also has forensic value. A mismatch can signal that a file was compiled elsewhere, copied from another environment, or generated under conditions that do not match the current runtime expectations.

That makes it useful during analysis of Python environments where provenance matters. A bytecode file with an unexpected marker is a cue to verify how it was produced, where it came from, and whether the surrounding runtime is consistent with the rest of the environment.

In that sense, the magic number is a small but meaningful trust boundary. It does not prove the file is safe on its own, but it does help Python avoid executing bytecode that cannot be reliably interpreted.

Risk and Threat Considerations

Magic number mismatches are usually operational issues, but they can also expose build integrity problems. If bytecode appears in an environment where it should not have been produced, the mismatch can reveal version drift, stale artifacts, or unexpected file movement across systems.

Failure mechanism: An interpreter reads a .pyc file whose header was generated by a different Python version, so the loader rejects it or raises a bad magic number error instead of executing incompatible bytecode.

Impact: Imports fail, deployments break, and analysts lose confidence in whether compiled artifacts match the intended runtime. In mixed or poorly controlled environments, repeated mismatches can also obscure deeper packaging or integrity problems.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.

Framework	Control / Reference	Relevance
CIS Controls v8	CIS 16 — Application Software Security	Compiled artifacts must be version-matched and validated before runtime use.
Recommendation — Verify Python bytecode and deployment artifacts against the target runtime before release.
NIST CSF 2.0	PR.IP-1 — Configuration Management	The magic number is a configuration signal tied to interpreter version consistency.
	DE.CM-8 — Vulnerability Scans and Integrity Checks	A bad magic number is an integrity signal that compiled files do not match the active runtime.
Recommendation — Track interpreter versions and rebuild compiled caches when runtime versions change. Use integrity checks to detect stale or mismatched Python bytecode in deployed environments.

Magic Number