Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

A program fails to start because libpq.so.5 is missing

Errorerror while loading shared libraries: libpq.so.5: cannot open shared object file: No such file or directory

Short 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.

  • Applies to Ubuntu 24.04, Debian 12, psycopg 3, psycopg2 2.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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__)')"
  2. 2Match what you see, then jump to its fix

    1. 1ldd prints libpq.so.5 => not found, and no libpq file exists anywhereThe libpq runtime package is not installed on this machineFix
    2. 2find shows libpq.so.5 under a custom prefix, while ldd says not foundlibpq exists, but in a folder the loader does not searchFix
    3. 3ldd 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

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 libpq

2Fix

Install the runtime library. On Debian and Ubuntu the package is libpq5.

sudo apt install libpq5

3Verify

The loader finds the library.

ldconfig -p | grep libpq.so.5

Confirmed by psycopg.org

Did this fix it?

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/null

2Fix

Add that folder to LD_LIBRARY_PATH for the process that starts the program.

export LD_LIBRARY_PATH=/opt/postgres/lib:$LD_LIBRARY_PATH

3Verify

ldd no longer reports it as not found.

ldd "$(python -c 'import psycopg2._psycopg as m; print(m.__file__)')" | grep libpq

Confirmed by psycopg.org

Did this fix it?

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 libpq

2Fix

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

Did this fix it?

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

Next step

Want this handled for good?

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