A program fails to start because libpq.so.5 is missing
error while loading shared libraries: libpq.so.5: cannot open shared object file: No such file or directoryShort answer
A program linked to PostgreSQL's client library cannot find libpq.so.5 at run time. Install the libpq package, point the loader at a non-standard folder with LD_LIBRARY_PATH, or switch a Python app to a package that bundles its own libpq. Check with ldd which library the module expects.
Fix it fast
1Find out which cause you have
Ask the dynamic loader which libraries the failing program or Python module cannot resolve.
ldd /path/to/failing-program | grep -i "libpq\|not found" # for psycopg2 ldd "$(python -c 'import psycopg2._psycopg as m; print(m.__file__)')"2Match what you see, then jump to its fix
- 1
ldd prints libpq.so.5 => not found, and no libpq file exists anywhereThe libpq runtime package is not installed on this machineFix - 2
find shows libpq.so.5 under a custom prefix, while ldd says not foundlibpq exists, but in a folder the loader does not searchFix - 3
ldd shows psycopg2/_psycopg.so resolving to an unexpected libpq, or a version mismatch errorThe module is linked to a different libpq than the one installedFix
- 1
What does the error look like?
error while loading shared libraries: libpq.so.5: cannot open shared object file: No such file or directory
Cause 1 of 3
The libpq runtime package is not installed on this machine
1Check
Pure Python psycopg loads libpq from the system through ctypes, and a source-built psycopg2 links to it, so the library must be present at run time.
ldconfig -p | grep libpq2Fix
Install the runtime library. On Debian and Ubuntu the package is libpq5.
sudo apt install libpq53Verify
The loader finds the library.
ldconfig -p | grep libpq.so.5Confirmed by psycopg.org
Cause 2 of 3
libpq exists, but in a folder the loader does not search
1Check
If the library is in a non-standard location, the operating system must be told where to look. Locate the file first.
find / -name 'libpq.so*' 2>/dev/null2Fix
Add that folder to LD_LIBRARY_PATH for the process that starts the program.
export LD_LIBRARY_PATH=/opt/postgres/lib:$LD_LIBRARY_PATH3Verify
ldd no longer reports it as not found.
ldd "$(python -c 'import psycopg2._psycopg as m; print(m.__file__)')" | grep libpqConfirmed by psycopg.org
Cause 3 of 3
The module is linked to a different libpq than the one installed
1Check
For import errors about missing or mismatched libraries, the psycopg2 docs say to check with ldd that the compiled module links to the right libpq.so.
ldd "$(python -c 'import psycopg2._psycopg as m; print(m.__file__)')" | grep libpq2Fix
Install the binary package, which carries its own libraries, instead of a source build against the system one. For psycopg 3 that is the binary extra.
python -m pip uninstall -y psycopg2
python -m pip install psycopg2-binary
# psycopg 3
python -m pip install "psycopg[binary]"3Verify
The import works without any system libpq.
python -c "import psycopg2; print(psycopg2.__version__)"Confirmed by psycopg.org
How do I stop it coming back?
- In Dockerfiles, install libpq5 in the final stage, not only in the build stage.
- Choose psycopg[binary] or psycopg2-binary for simple deployments; use a source build only when you need to match the system libraries.
- Run ldd on the module during image builds so a missing library fails the build.
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?
Related fixes
Databases
Python cannot import psycopg2 even though you installed it
No module named 'psycopg2.extensions'
Python found no psycopg2 package in the interpreter that runs your code.
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
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
manage.py test stops with 'permission denied to create database' on PostgreSQL
django.db.utils.ProgrammingError: permission denied to create database
Django creates a separate database called test_ plus your database name, using the DATABASES USER.
2 causes, each with a fix