How to install psycopg2 with "pip" on Python?

System-specific psycopg2 installation

Different operating systems might require divergent approach for successful psycopg2 installation. Let's discuss what fits best for each environment.

Pre-installation checklist for source compilation

Before getting hands dirty with installing psycopg2 from source, make sure to check off these required system dependencies. If you are on a Debian-based distribution (Ubuntu):

# Let's invite the necessary guests for our psycopg2 party!
sudo apt-get install libpq-dev python3-dev


For those loyal to Red Hat-based distributions such as CentOS:

# Red Hat rocks, doesn't it? 🎩
sudo yum install python-devel postgresql-devel


macOS users might need to ask Homebrew for a favour of installing PostgreSQL to ward off the unwelcomed "pg_config" error:

# Brew something magical to sweep off the pg_config nuisance
brew install postgresql


Overcoming the "pg_config not found" speed bump

If your installation journey bounces over the "pg_config not found" speed bump, give your PATH environment variable a glimpse of the PostgreSQL bin directory:

# Show pg_config the path to enlightenment
export PATH="/path/to/PostgreSQL/bin:$PATH"


Or steer the psycopg2 installation with the pg_config path directly:

# Here, psycopg2, let me show you the way
pip install --global-option=build_ext --global-option="-I/usr/include/postgresql" psycopg2


For Mac users, optionally installing the craftsmen build-essential or postgresql-server-dev-all tools might turn out to be handy.

In the realm of Windows

In the midst of Windows, you may fancy the psycopg2 windows binaries. A word to the wise, bear in mind the naming conventions (psycopg2 vs. psycopg2-binary) when inviting psycopg2 into your Windows household.

Launch your virtualenv like a pro:

path\to\env\Scripts\activate.bat  # "Open Sesame!" for the magical virtual environment
pip install psycopg2-binary    # Landing the psycopg2 binary in one swoop


Before inviting psycopg2 into your virtual environment

Remember to open the gates of your virtual environment before inviting psycopg2:

# Let's step into our serene and isolated zen garden
source path/to/env/bin/activate
pip install psycopg2   # Summoning psycopg2 in the peaceful virtual environment


Installing psycopg2 into a sanitized virtual environment is like keeping your books organized on a separate bookshelf, far from the cluttered global library.

Troubleshooting and verification guide

Before diving into psycopg2 installation, ensure to validate your PostgreSQL installation and check if the service is running like a finely tuned orchestra. Not all errors are monsters under your bed, some might just be your guiding light to the correct installation process. If you meet a stubborn trouble, escape to the GitHub issues page linked in the References below.

Environment compatibility affairs

Sometimes, it's not about the path you walk, but who walks with you. Verify your system path and environment variables are in harmony with PostgreSQL's installation path. Relinking or reinstalling PostgreSQL, is like adjusting your compass if it's not pointing north due to recent changes in your system landscape.

Escalating permissions when needed

You might need to wear your superuser cape in Linux/macOS to elevate installation permissions:

sudo pip install psycopg2  # Superuser powers... activate!


Accessing the Windows binary fortress

March straight to the binary package for Windows from the official psycopg2 PyPI page and grab the version that syncs with your Python rhythm.