Skip to content
Nilay Kabariya

Entry No.104·Database··4 min read

SQLAlchemy 2.1: 'greenlet' library is required (asyncio)

SQLAlchemy 2.1 no longer installs greenlet, so async engines fail unless something else adds it. Install sqlalchemy[asyncio]. Tested on 2.0.57 and 2.1.8.

by Nilay#python#sqlalchemy#asyncioDATABASE

The error, verbatim

Jump to the fix ↓
ImportError: The SQLAlchemy asyncio module requires that the Python 'greenlet' library is installed.  In order to ensure this dependency is available, use the 'sqlalchemy[asyncio]' install target:  'pip install sqlalchemy[asyncio]'

The fix that worked

Install SQLAlchemy with its asyncio extra:

pip install "sqlalchemy[asyncio]"
Not it? Every cause, tested ↓

Tested on

SQLAlchemy
2.0.57 and 2.1.8
Drivers
aiosqlite, asyncpg (the latest releases on November 9, 2026)
Python
3.11.18 and 3.14.10
Where
GitHub Actions ubuntu-latest

✓ Last re-run on GitHub Actions · see the run · all repros

Your async code didn’t change. Your install did. Up to SQLAlchemy 2.0, pip install sqlalchemy quietly brought greenlet along on the usual platforms, and that’s what SQLAlchemy’s async engine runs on. From 2.1 it doesn’t. greenlet moved into the optional asyncio extra, so a fresh environment with pip install sqlalchemy aiosqlite (or asyncpg) now gets SQLAlchemy without it, and the first awaited query stops with the ImportError above. Any requirements file that floats to 2.1 hits this the next time it’s rebuilt.

Ask for the extra, which brings greenlet with it:

pip install "sqlalchemy[asyncio]"

In requirements.txt or pyproject.toml, write it the same way: sqlalchemy[asyncio]>=2.1.

Five installs, one async query

I ran the same three-line async query (select 1 through create_async_engine) after five different installs, each in a fresh virtual environment, on November 9, 2026:

Terminal on GitHub Actions with Python 3.11: SQLAlchemy 2.0.57 with aiosqlite installs greenlet and the async query works; 2.1.8 with aiosqlite or asyncpg has no greenlet and fails with ImportError: The SQLAlchemy asyncio module requires that the Python greenlet library is installed; sqlalchemy[asyncio] 2.1.8 or adding greenlet works; a sync engine on 2.1 works without greenlet; the 2.1.8 metadata shows Requires-Python >=3.11 and greenlet only under extra asyncio.
Python 3.11.18; Python 3.14.10 printed the same results. Full log.
Install greenlet present? Async query
sqlalchemy==2.0.* + aiosqlite yes works
sqlalchemy==2.1.* + aiosqlite no ImportError
sqlalchemy==2.1.* + asyncpg no ImportError
sqlalchemy[asyncio]==2.1.* + aiosqlite yes works
sqlalchemy==2.1.* + aiosqlite + greenlet yes works

The package metadata says the same thing. SQLAlchemy 2.1.8 lists greenlet>=1 only under extra == "asyncio", and its only unconditional dependency is typing-extensions.

What the error is (and isn’t) telling you

Two details are easy to misread:

  • It’s not a missing driver. asyncpg and aiosqlite were both installed and fine. The message names greenlet because SQLAlchemy’s async layer is built on top of it; the driver is never reached.
  • Older answers point elsewhere. Earlier versions of this problem, with a ValueError: the greenlet library is required wording, were usually about Apple Silicon Macs (where 2.0’s install rule skipped greenlet) or platforms with no greenlet wheel, and those answers tell you to install greenlet or build tools. On 2.1 the cause is packaging for every platform, and the fix is one extra. If you see the 2.1 ImportError wording above, you’re in this case.

Synchronous code isn’t affected. A plain create_engine on 2.1.8 ran select 1 without greenlet installed, so a mixed project can work in some scripts and fail only in the async ones.

When a library installs SQLAlchemy for you

Often SQLAlchemy isn’t in your own requirements at all; something else brings it. Whether you get greenlet then depends on how that library asks for it. Their published requirements, checked on November 16, 2026:

Library How it requires SQLAlchemy greenlet on 2.1?
sqlmodel 0.0.50 SQLAlchemy>=2.0.14,<2.2.0; [asyncio] only with sqlmodel[asyncio] only if you install sqlmodel[asyncio]
alembic 1.20.1 SQLAlchemy>=2.0 no
databases 0.9.0 sqlalchemy>=2.0.7 no
advanced-alchemy 1.12.0 sqlalchemy>=2.0.41 plus greenlet directly yes
fastapi-users-db-sqlalchemy 7.0.0 sqlalchemy[asyncio]>=2.0.0,<2.1.0 yes, but it holds you on 2.0

So with SQLModel, the async fix is pip install "sqlmodel[asyncio]", not a separate greenlet line, and a project using databases or plain Alembic needs the extra in its own requirements. fastapi-users-db-sqlalchemy avoids the error a different way: it caps SQLAlchemy below 2.1, so you won’t get 2.1 at all while it’s installed. These come from each package’s metadata on PyPI, not from running them.

Python 3.10 can’t take 2.1 at all

SQLAlchemy 2.1 requires Python 3.11 or newer (Requires-Python: >=3.11). On 3.10, pip doesn’t raise an error; it quietly installs the newest 2.0 release instead, which still brings greenlet. So the same pip install sqlalchemy aiosqlite whose async query fails on 3.11 can work on 3.10, on an older SQLAlchemy than you think. Python 3.10 reached end of life on October 1, 2026, so expect more of this; pip show sqlalchemy tells you which line you’re on.

The run

GitHub Actions ubuntu-latest, Python 3.11.18 and 3.14.10, November 9, 2026. Each of the five installs was a fresh venv with the newest release in each line (2.0.57 and 2.1.8) and the latest aiosqlite and asyncpg. The test was an async engine on an in-memory SQLite database running select 1; the asyncpg case fails before any connection is attempted, so it needed no database server. The script and both runs are public.

— N.K., end of entry No.104

Useful? Pass it on:Post on XFollow @EmotionalMatter

Related entries

  1. No.106

    Python 3.10 end of life: 14 of 47 packages quietly downgrade

    Nothing fails to install on Python 3.10 yet. pip resolves to the last release that still supports 3.10, with no warning: numpy 2.2.6 instead of 2.5.4, pandas 2.3.3 instead of 3.1.1, Django 5.2 instead of 6.1, SQLAlchemy 2.0 instead of 2.1, and 10 more of the 47 I tried. You only see an error when you pin the newest version.

    TESTED5 min
  2. No.098

    huggingface-cli: command not found (removed in 1.0, not 2.0)

    huggingface-cli stopped working in huggingface_hub 1.0.0, returned as a do-nothing stub in 1.10.1 and is gone in 2.0. All versions tested, plus the hf commands.

    > huggingface-cli: command not found

    AI5 min
  3. No.094

    Python CERTIFICATE_VERIFY_FAILED, tested on 3.12 to 3.15

    certificate verify failed: unable to get local issuer certificate, or Basic Constraints of CA cert not marked critical on Python 3.13+. Each cause tested.

    > requests.exceptions.SSLError: HTTPSConnectionPool(host='pypi.org', port=443): Max retries exceeded with url: /simple/

    FIXED3 minWindows

tip: paste the exact error text