Introduction

Installing psycopg2 is usually easy until native dependencies get involved. The package connects Python to PostgreSQL, so depending on which distribution you choose, pip may either download a ready-made wheel or try to compile against system PostgreSQL libraries.

The first decision is whether you want psycopg2-binary for convenience or psycopg2 for a source-based build. Once that is clear, most installation problems become much easier to diagnose.

Start in the Correct Python Environment

Before installing anything, confirm which interpreter and pip you are about to use. A large percentage of installation issues come from putting the package into the wrong environment.

python3 --version
python3 -m pip --version
which python3

A virtual environment is the safest setup:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Using python -m pip ties the install command to the active interpreter, which avoids confusion when a system Python and a project Python both exist.

Choose Between psycopg2-binary and psycopg2

For local development, the easiest command is usually:

python -m pip install psycopg2-binary

That package ships prebuilt wheels for many common environments, so there is often no compilation step.

If you need the source package instead, run:

python -m pip install psycopg2

The source version can be the right choice when your deployment standards prefer linking against system libraries, but it is also the version most likely to fail if build prerequisites are missing.

Understand the pg_config Error

One of the most common failures looks like a complaint about pg_config not being found. That usually means pip is trying to build psycopg2 from source, but the PostgreSQL client development tools are not installed on the machine.

In that situation, you have two paths:

• install the PostgreSQL development libraries for your operating system and retry
• switch to psycopg2-binary if a wheel is acceptable for your environment

This is a system dependency problem, not a Python syntax problem.

Verify the Installation with an Import

Do not stop at a successful install log. Confirm that Python can actually import the driver:

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

If that command fails with ModuleNotFoundError, the package probably went into a different environment than the one you are using.

Test a Real Connection

The next step is proving the installed package can talk to PostgreSQL. A simple connection test is enough:

1import psycopg2
2
3conn = psycopg2.connect(
4    host="localhost",
5    port=5432,
6    dbname="postgres",
7    user="postgres",
8    password="postgres",
9)
10
11with conn:
12    with conn.cursor() as cur:
13        cur.execute("SELECT 1")
14        print(cur.fetchone())

If the import works but the connection fails, the package installation is done and the remaining problem is database connectivity or credentials.

Keep the Installation Choice Deliberate

It is tempting to bounce between package names until something installs. That usually makes the environment less understandable. Pick one path intentionally:

• 'psycopg2-binary for the fastest local setup'
• 'psycopg2 when your environment requires source builds and system-level library control'

That clarity helps later when another developer reproduces the environment or when a container image is built in CI.

Common Pitfalls

• Running pip install against one Python interpreter and executing code with another.
• Installing psycopg2 from source without PostgreSQL development tools present.
• Treating psycopg2 and psycopg2-binary as interchangeable without understanding why the project prefers one.
• Assuming a successful install log is enough without testing an import.
• Debugging SQL credentials before proving the driver is installed correctly.

Summary

• Use a virtual environment and run installs with python -m pip.
• 'psycopg2-binary is usually the simplest option for development.'
• 'psycopg2 source installs need PostgreSQL build dependencies.'
• Verify the result with both an import test and a real connection.
• Separate packaging issues from database connectivity issues when debugging.