Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

SQLAlchemy cannot load the dialect plugin for a postgres:// URL

Errorsqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres

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

  • Applies to SQLAlchemy 2.0, Flask-SQLAlchemy 3.1, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1Can't load plugin: sqlalchemy.dialects:postgres, usually right after upgrading SQLAlchemy to 1.4 or later or after copying a URL from a hosting dashboardThe URL starts with postgres://Fix
    2. 2The plugin name in the message has an extra letter, for example postgressqlThe dialect name is misspelledFix

What does the error look like?

  • sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres
  • NoSuchModuleError: 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=*.ini

2Fix

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

Did this fix it?

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

3Verify

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

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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