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
Contents
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.](/shots/sqlalchemy-draft/run.webp)
| 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
greenletbecause 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 requiredwording, were usually about Apple Silicon Macs (where 2.0’s install rule skippedgreenlet) or platforms with nogreenletwheel, and those answers tell you to installgreenletor build tools. On 2.1 the cause is packaging for every platform, and the fix is one extra. If you see the 2.1ImportErrorwording 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