Python cannot import psycopg2 even though you installed it
ModuleNotFoundError: 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.
Fix it fast
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-binary2Match what you see, then jump to its fix
- 1
pip says the package is installed, but the app's python still cannot import itpip installed the package into a different PythonFix - 2
The 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
pip 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
- 1
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 --version2Fix
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-binary3Verify
The import works with the same interpreter.
python -c "import psycopg2.extensions; print(psycopg2.__version__)"Confirmed by docs.python.org
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
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 --version2Fix
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 psycopg23Verify
The import succeeds.
python -c "import psycopg2.extensions as e; print(e.__name__)"Confirmed by psycopg.org
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
pip install psycopg2 fails with 'Failed building wheel for psycopg2'
error: Python.h: No such file or directory
psycopg2 is compiled from source when pip finds no ready wheel for your platform.
3 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
pip install mysqlclient fails to build on Windows, Linux or macOS
error: metadata-generation-failed
mysqlclient is a C extension.
3 causes, each with a fixDatabases
pyodbc cannot find the SQL Server ODBC driver on Linux
Can't open lib 'ODBC Driver 17 for SQL Server' : file not found
The driver manager looked for a driver library that is not installed or not registered under that name.
3 causes, each with a fixDatabases
pip cannot build the mariadb package because mariadb_config is missing
Please make sure, that MariaDB Connector/C is installed on your system.
The mariadb Python package builds against MariaDB Connector/C, and it finds the library through the mariadb_config program.
3 causes, each with a fixDatabases
asyncpg InterfaceError: another operation is in progress with SQLAlchemy
InterfaceError raised from a FastAPI endpoint that runs several queries at once
A single database connection can run one operation at a time.
4 causes, each with a fix