Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Python cannot import psycopg2 even though you installed it

ErrorModuleNotFoundError: No module named 'psycopg2'

Short answer

Python found no psycopg2 package in the interpreter that runs your code. Either pip installed it into a different Python, a file or folder named psycopg2 in your project hides the real package, or it was never installed. Install with python -m pip using the same interpreter that runs the app.

  • Applies to Python 3.12 and 3.13, psycopg2 2.9, Django 5.2, Ubuntu 24.04 and Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the exact interpreter that fails where it looks for modules and whether it can find psycopg2 at all.

    python -c "import sys; print(sys.executable)"
    python -m pip show psycopg2 psycopg2-binary
  2. 2Match what you see, then jump to its fix

    1. 1pip says the package is installed, but the app's python still cannot import itpip installed the package into a different PythonFix
    2. 2The package is installed for this interpreter, but the import still fails or misses submodulesA local file or folder named psycopg2 hides the real packageFix
    3. 3pip show prints nothing, or the install log ended in a build error about libpq-fe.h, Python.h or pg_configThe driver is not installed, or its source build failedFix

What does the error look like?

  • ModuleNotFoundError: No module named 'psycopg2'
  • No module named 'psycopg2.extensions'

Cause 1 of 3

pip installed the package into a different Python

1Check

pip and python on your PATH can belong to different installations, for example a system Python and a virtual environment. Compare the interpreter path with what pip reports.

python -c "import sys; print(sys.executable)"
python -m pip --version

2Fix

Call pip through the interpreter that runs the app, using -m. On Windows use the py launcher with a version.

python3 -m pip install psycopg2-binary
# Windows
py -3.13 -m pip install psycopg2-binary

3Verify

The import works with the same interpreter.

python -c "import psycopg2.extensions; print(psycopg2.__version__)"

Confirmed by docs.python.org

Did this fix it?

Cause 2 of 3

A local file or folder named psycopg2 hides the real package

1Check

The directory of the running script comes first on the module search path, ahead of installed packages. A file such as psycopg2.py or a folder psycopg2/ next to your code is loaded instead.

ls psycopg2.py psycopg2 2>/dev/null
python -c "import psycopg2; print(psycopg2.__file__)"

2Fix

Rename the local file or folder, and delete its __pycache__ entry. Then import the real package.

mv psycopg2.py db_connect.py
rm -rf __pycache__

3Verify

The printed path now points into site-packages.

python -c "import psycopg2; print(psycopg2.__file__)"

Confirmed by docs.python.org

Did this fix it?

Cause 3 of 3

The driver is not installed, or its source build failed

1Check

A plain psycopg2 install builds from source and needs a C compiler, the Python headers, libpq headers and pg_config. The pre-built psycopg2-binary package skips all of that.

pg_config --version

2Fix

Install the pre-built package for development. The psycopg docs advise building from source for production, which means installing the build prerequisites first.

python -m pip install psycopg2-binary

# production, Debian or Ubuntu
sudo apt install python3-dev libpq-dev
python -m pip install psycopg2

3Verify

The import succeeds.

python -c "import psycopg2.extensions as e; print(e.__name__)"

Confirmed by psycopg.org

Did this fix it?

How do I stop it coming back?

  • Work in a virtual environment per project and always call python -m pip.
  • Never name your own file after a package you import.
  • Pin the driver in requirements.txt so a fresh machine installs the same one.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.