ModuleNotFoundError: No module named 'psycopg2'

How to fix ModuleNotFoundError: No module named 'psycopg2'

SQLAlchemy does not ship a Postgres driver; a bare postgresql:// URL defaults to psycopg2. Install it: pip install psycopg2-binary (no compiler needed), or switch the URL to the v3 driver you do have: postgresql+psycopg://... with pip install "psycopg[binary]". The driver name in the URL must match the installed package.

The exact error

ModuleNotFoundError: No module named 'psycopg2'

Fix it

1. Check which driver you have: python -m pip show psycopg2-binary psycopg. Expected: you see which (if any) is installed

2. Easiest: python -m pip install psycopg2-binary and keep postgresql://. Expected: create_engine connects

3. Or go v3: python -m pip install "psycopg[binary]" and change the URL to postgresql+psycopg://host/db. Expected: connects via psycopg3

When this applies

create_engine('postgresql://...') raises No module named 'psycopg2'

When this does NOT apply

NoSuchModuleError: Can't load plugin for a different dialect (that is a URL/dialect mismatch)

Versions

SQLAlchemy with postgresql:// URLs

Why it happens

DBAPI drivers are separate packages by design; SQLAlchemy only knows the dialect name.

Edge cases

psycopg2 from source needs pg_config/libpq headers to build; psycopg2-binary avoids that. Keep the password in env vars, not code.

Asked about: ModuleNotFoundError: No module named 'psycopg2' (gh:zzstoatzz/plyr.fm#1584). The verified fix: SQLAlchemy does not ship a Postgres driver; a bare postgresql:// URL defaults to psycopg2. Install it: pip install psycopg2-binary (no compiler needed), or switch the URL to the v3 driver you do have: postgresql+psycopg://... with pip install "psycopg[binary]". The driver name in the URL must match the installed package. Full thread: https://github.com/zzstoatzz/plyr.fm/issues/1584