Fix the Bad Magic Number in sqlite3

A Python program that uses SQLite needs Python to load sqlite3 before it can work with a database. The sqlite3 module lets Python connect to SQLite and run queries.

In this piece, I’ll explain what “bad magic number” means and show how to check which module Python loads before choosing a fix.

TL;DR: Fix the sqlite3 Import Error

Check which file Python resolves as sqlite3, then rename a conflicting project file or remove only the confirmed incompatible cache file.

• Run the diagnostic from the same directory and interpreter as the failing program.
• If the origin points into your project, rename sqlite3.py or the sqlite3 directory.
• If the origin is the standard library, check which Python runs the program and inspect its cache files.
• Run a small import and query to verify the fix.

Diagnostic result	Next action
Origin points into the project	Inspect for a conflicting sqlite3.py file or sqlite3 directory
Origin points to the standard library	Compare the failing interpreter and inspect the exact traceback path

What Does the Bytecode Error Mean?

A “bad magic number” means Python tried to read compiled bytecode whose header does not match a format it accepts. Python compiles source modules into bytecode and stores cached copies in .pyc files.

The name in the error identifies the module Python was loading, not necessarily the file you meant to use. Python searches its import path, which includes the current working directory, so a project file named sqlite3.py or a directory named sqlite3 can take precedence over the standard-library package.

These are two related checks, not proof of one cause. An incompatible cache can fail while Python reads a module, while a same-named project file can redirect the import. The traceback path and resolved origin tell you which branch to investigate.

This issue is about locating the module and its bytecode. A missing _sqlite3 extension is a different installation problem. See the SQLite error codes reference for database-engine errors, and Python sqlite3 parameterized queries for query handling after the import works.

Symptom	What it points to	Check
Traceback names a project sqlite3.py	Local module shadows the library	Rename the file and check find_spec() again
Traceback names a .pyc file	Python cannot read that cached bytecode	Confirm its source and interpreter before removing it
No module named _sqlite3	Extension is absent from the Python build	Diagnose the Python installation separately

The distinction matters because the fixes are different. Renaming a project module will not add a missing extension to Python, and reinstalling Python will not correct a project file that takes precedence on the import path.

How to Fix the sqlite3 Import Error

To fix the import, identify the module Python resolves and apply a repair only to that path. I ran the check below from this workspace and found the standard-library package.

Step 1: Check the sqlite3 module origin

Python’s find_spec() reports the module specification and its origin without importing application code. Save this as sqlite3_origin_check.py and run it from the project directory with the interpreter that fails.

import importlib.util

spec = importlib.util.find_spec("sqlite3")
print(spec.origin.rsplit("/", 2)[-2:])

['sqlite3', '__init__.py']

The output lists the last two path components so you can recognize the package without copying an environment-specific directory. If the full origin is inside your project, inspect that file or directory before changing any cache.

For a more direct diagnostic, print the complete origin rather than trimming the path. This helps distinguish candidates in a project, virtual environment, and system library.

Step 2: Rename a local sqlite3 module

A project file named sqlite3.py, or a project package directory named sqlite3, can shadow the standard library. Rename the project code to a task-specific name, then remove only its matching cached file under that project’s __pycache__ directory if one exists.

mv sqlite3.py app_database.py

Use the rename only when the diagnostic points to a project-local conflict. Update imports that referred to the old name, and check for a package directory with the same name. Remove a cache only after confirming that it belongs to this module.

Do not rename files under Python’s installation directories. Also check the script’s directory and the current working directory, because both can affect module resolution. I choose to rename the source file first because it fixes the name collision without altering the Python installation.

Step 3: Confirm the interpreter and bytecode cache

If find_spec() points to the standard library, compare the Python executable used by your command, IDE, service, or virtual environment. A .pyc produced for a different interpreter can be rejected because its bytecode header does not match the running interpreter.

Run the diagnostic under the same launch method as the failing application. An IDE may select a virtual environment while a terminal command selects another interpreter. Compare their executable paths as well as version strings.

python3 -V
python3 sqlite3_origin_check.py

Python 3.14.7
origin: ['sqlite3', '__init__.py']
SQLite: 3.53.1
query: 1

Those commands ran here and show this environment’s interpreter and module location. Run them in your environment, not by copying the displayed path. If the error path is a project cache, remove only that identified .pyc and rerun the import.

Python can rebuild a cache from its matching source when the module loads. If that source is missing, restore it from the package or environment that owns it instead of deleting unrelated caches. A cache filename alone does not identify the right file.

Step 4: Verify the import and a SQLite query

After correcting the confirmed cause, import sqlite3 and run a harmless query against an in-memory database. This checks both module loading and the SQLite connection path without creating a database file.

import sqlite3

connection = sqlite3.connect(":memory:")
print(connection.execute("select 1").fetchone()[0])
connection.close()

1

I ran this query successfully in the workspace. If your program still fails, run the diagnostic from its actual launch directory and check that it uses the same interpreter as the command above.

The in-memory database avoids changing a project file while testing. A successful result confirms this interpreter loaded sqlite3 and executed the query. It does not verify an IDE or service that selects a different interpreter.

Edge Cases: Bytecode and Name Collisions

Match the repair to the path and file named by the traceback. Removing unrelated bytecode or reinstalling Python before identifying that path can hide the cause without fixing module resolution.

What the origin or traceback shows	Likely cause	Next check
A project path ending in sqlite3.py	Local module shadows the standard library	Rename the file and update imports that refer to it
A project sqlite3 directory	Local package shadows the standard library	Rename the directory and remove only its matching project cache
Standard-library path with a bytecode error	Interpreter mismatch or stale compiled file	Compare interpreter paths and inspect the exact .pyc in the traceback
No module named _sqlite3	SQLite extension missing from the Python build	Use the separately diagnosed installation/build route

The traceback’s filename is the useful clue. Prefer the narrowest fix that matches it, then verify from the same launch context because another environment can resolve a different sqlite3 module.

A traceback that names a project file identifies the module Python tried to load. Limit cache removal to a file you confirmed belongs to that module. When a package directory has the same name, rename that directory too because it can still win on the next import.

If the traceback points into the standard library, compare how the failing process starts with the command-line check. Services and IDEs can keep separate interpreter selections. Correct that selection first, then retest before changing installed files.

Conclusion: Check the Resolved sqlite3 Module

A bad magic number points to bytecode Python cannot accept, while a local sqlite3 name can send the import to the wrong module in the first place. Check the origin, correct only the identified collision or cache, and verify with a small query.

For follow-up, see the Python import system documentation and the sqlite3 module reference.

FAQ

These answers cover the two checks that separate a name collision from a bytecode problem.