Install & Compatibility
Where this runs
tested against v0.31.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.320s · 26.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.272s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from asyncpg import Connection
asyncpg-stubs provides type hints for symbols imported from the 'asyncpg' library; you do not typically import directly from 'asyncpg_stubs'.
Pool
✓ from asyncpg import Pool
asyncpg-stubs provides type hints for symbols imported from the 'asyncpg' library; you do not typically import directly from 'asyncpg_stubs'.
Record
✓ from asyncpg import Record
asyncpg-stubs provides type hints for symbols imported from the 'asyncpg' library; you do not typically import directly from 'asyncpg_stubs'.
This example demonstrates a basic connection and query using `asyncpg`. When `asyncpg-stubs` is installed, type checkers (like MyPy or Pyright) will provide precise type hints for `asyncpg.Connection`, `asyncpg.Record`, and other asyncpg objects and methods used in this code, improving developer experience and catching potential type errors statically.
import asyncio
import asyncpg
import os
async def main():
# asyncpg-stubs provides type hints for asyncpg objects like Connection and Record.
# Replace with your PostgreSQL connection string or use environment variables.
# Example: DATABASE_URL='postgresql://user:password@localhost:5432/testdb'
conn_string = os.environ.get('DATABASE_URL', 'postgresql://user:password@localhost:5432/testdb')
conn: asyncpg.Connection | None = None
try:
conn = await asyncpg.connect(conn_string)
print("Connected to PostgreSQL database.")
# Execute a simple query
result: str = await conn.fetchval("SELECT 'Hello from asyncpg!'")
print(f"Query result: {result}")
# Example with parameters and fetching a record
await conn.execute('''
CREATE TABLE IF NOT EXISTS my_table (
id serial PRIMARY KEY,
name text
);
''')
await conn.execute("INSERT INTO my_table(name) VALUES($1)", "Test User")
record: asyncpg.Record | None = await conn.fetchrow("SELECT id, name FROM my_table WHERE name = $1", "Test User")
if record:
print(f"Fetched record: ID={record['id']}, Name={record['name']}")
except Exception as e:
print(f"Error: {e}")
finally:
if conn:
await conn.close()
print("Connection closed.")
if __name__ == "__main__":
asyncio.run(main())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'asyncpg'
The 'asyncpg' module is not installed in the current Python environment.
fixInstall 'asyncpg' using pip: 'pip install asyncpg'.
ImportError: cannot import name 'create_pool' from 'asyncpg'
The 'create_pool' function is not available in the 'asyncpg' module, possibly due to an outdated version.
fixEnsure you have the latest version of 'asyncpg' installed: 'pip install --upgrade asyncpg'.
TypeError: 'NoneType' object is not callable
Attempting to call a function that is 'None', possibly due to a failed import or incorrect assignment.
fixVerify that all imports are correct and that the functions are properly defined before calling them.
AttributeError: module 'asyncpg' has no attribute 'connect'
The 'connect' attribute is missing from the 'asyncpg' module, possibly due to an incorrect installation or version mismatch.
fixReinstall 'asyncpg' to ensure a correct installation: 'pip install --force-reinstall asyncpg'.
SyntaxError: invalid syntax
There is a syntax error in the code, possibly due to using an async function incorrectly.
fixEnsure that async functions are defined with the 'async def' syntax and called with 'await'.
Upgrade
Version history
0.31.3latest on PyPI · released Jul 10, 2026
Audit
Dependencies
asyncpgrequiredProvides the runtime library for which these stubs offer type annotations. The stub's major.minor version should ideally match the asyncpg version used.
typing-extensionsrequiredRequired for advanced type hint features used within the stubs.