SQLAlchemy cannot load the dialect plugin for a postgres:// URL
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgresShort answer
SQLAlchemy looks up the first part of the database URL as a dialect name. postgres is not a dialect name in SQLAlchemy 1.4 and later, so the lookup fails. Change the scheme to postgresql, or postgresql+psycopg2 to name the driver. If the URL comes from a host that gives you a postgres:// value, rewrite the prefix in code.
Fix it fast
1Find out which cause you have
Print the scheme your app really passes to create_engine, as seen after environment variables and config files are applied. The text before :// is the dialect name SQLAlchemy tries to load.
python -c "import os; print(os.environ.get('DATABASE_URL', '').split('://')[0])"2Match what you see, then jump to its fix
What does the error look like?
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgresNoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgressql
Cause 1 of 2
The URL starts with postgres://
1Check
The maintainers' answer is that the proper scheme is postgresql, and that the postgres name was deprecated for years before SQLAlchemy 1.4 dropped it. libpq itself accepts both spellings, which is why the same URL works in other tools.
grep -rn "postgres://" . --include=*.py --include=*.env --include=*.cfg --include=*.ini2Fix
Use postgresql:// in the config. When the value is injected by a platform you do not control, rewrite the prefix before create_engine.
import os
from sqlalchemy import create_engine
url = os.environ["DATABASE_URL"]
if url.startswith("postgres://"):
url = url.replace("postgres://", "postgresql://", 1)
engine = create_engine(url)3Verify
Open a connection and run a trivial query.
from sqlalchemy import text
with engine.connect() as conn:
print(conn.execute(text("select 1")).scalar())Confirmed by github.com
Cause 2 of 2
The dialect name is misspelled
1Check
SQLAlchemy takes the name literally. A typo in the scheme fails in the same way as an unknown dialect. Compare your URL with the documented form dialect+driver://username:password@host:port/database.
python -c "import os; print(os.environ['DATABASE_URL'][:25])"2Fix
Write the scheme as postgresql, or postgresql+psycopg2 for the default driver. psycopg 3 is postgresql+psycopg.
# default driver (psycopg2)
postgresql://user:password@localhost/mydb
# psycopg 3
postgresql+psycopg://user:password@localhost/mydb3Verify
Create the engine again; no exception is raised, and a query returns.
python -c "from sqlalchemy import create_engine, text; e = create_engine('postgresql://user:password@localhost/mydb'); print(e.dialect.name)"Confirmed by docs.sqlalchemy.org
How do I stop it coming back?
- Keep the scheme in the settings file in the postgresql:// form and build the full URL in one place.
- After a SQLAlchemy upgrade, run one connection test in CI before deploying.
- Use URL.create() when the password contains special characters, instead of pasting it into a string.
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?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
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
asyncpg InterfaceError: another operation is in progress with SQLAlchemy
InterfaceError raised from a FastAPI endpoint that runs several queries at once
A single database connection can run one operation at a time.
4 causes, each with a fixDatabases
Django cannot load MySQLdb and asks whether mysqlclient is installed
Error loading MySQLdb module: Did you install mysqlclient or MySQL-python?
Django's MySQL backend imports MySQLdb, which is provided by the mysqlclient package.
3 causes, each with a fixDatabases
python manage.py migrate finishes but the tables for my app are missing
relation "myapp_book" does not exist
migrate only applies migration files that exist.
3 causes, each with a fixDatabases
Django save fails on PostgreSQL: null value in a column violates a not-null constraint
django.db.utils.IntegrityError: null value in column "price" of relation "shop_product" violates not-null constraint
A model field is NOT NULL in the database unless it has null=True.
3 causes, each with a fixDatabases
Django migration on PostgreSQL stops with 'pending trigger events'
django.db.utils.OperationalError: cannot ALTER TABLE "mytable" because it has pending trigger events
PostgreSQL runs a Django migration in one transaction.
2 causes, each with a fix