tortoise-orm

library1.1.8pypypi✓ verified 30d ago

Async ORM for Python inspired by Django ORM. Built on asyncio — requires async context. Current version: 1.1.7 (Mar 2026). v1.0 released 2024 — first stable release after years of 0.x. Breaking changes from 0.x: connections.close_all() removed, ConnectionHandler uses per-instance ContextVar storage. FastAPI integration changed from register_tortoise() to RegisterTortoise context manager. Does not work on serverless/Vercel without workarounds.

database web-framework aws

pip install tortoise-orm

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · TORTOISE-ORM

tortoise-orm

databasepythonv1.1.8

Install

3.0s avg

Import

1011ms

Disk

35MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.8 · 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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 1.043s · 33.9MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 3.0s · import 0.980s · 38MB

35MB installed

● package 35MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RegisterTortoise

✓ from tortoise.contrib.fastapi import RegisterTortoise

✗ from tortoise.contrib.fastapi import RegisterTortoise

Tortoise ORM v1.x standalone script with PostgreSQL.

# pip install 'tortoise-orm[asyncpg]' from tortoise import Tortoise, fields from tortoise.models import Model import asyncio class User(Model): id = fields.IntField(pk=True) name = fields.CharField(max_length=50) email = fields.CharField(max_length=120, unique=True) class Meta: table = 'users' async def main(): await Tortoise.init( db_url='postgres://user:pass@localhost/mydb', modules={'models': ['__main__']} ) await Tortoise.generate_schemas() # Create user = await User.create(name='Alice', email='alice@example.com') # Query users = await User.filter(name='Alice').all() user = await User.get(id=1) user = await User.get_or_none(email='alice@example.com') await Tortoise.close_connections() asyncio.run(main())

tortoise --version

Debug

Known issues

breakingconnections.close_all() removed in v1.0. Raises AttributeError.

fix

Use Tortoise.close_connections() instead.

affects: >= 1.0

breakingRunning multiple FastAPI apps in the same process (e.g., in tests) raises ConfigurationError: 'Global context fallback is already enabled'. Happens with lifespan-based testing.

fix

Pass _enable_global_fallback=False to RegisterTortoise for secondary apps.

affects: >= 1.0

gotchaMust use 'modules' dict when calling Tortoise.init() — must list all model module paths explicitly. Missing a module means those models are unknown to Tortoise and relations fail silently.

fix

modules={'models': ['myapp.models.user', 'myapp.models.post']} — list ALL model files.

affects: all

gotchatortoise-orm does not work on serverless/Vercel without workarounds. Connection pooling assumes long-running process — serverless cold starts cause 'connection pool is closed' errors.

fix

Not recommended for serverless. Use asyncpg directly or a serverless-compatible ORM.

affects: all

gotchagenerate_schemas=True in production silently drops and recreates tables if schema changes. Use Aerich (tortoise's migration tool) for production schema management.

fix

Set generate_schemas=False in production. Use aerich for migrations: pip install aerich

affects: all

gotchapydantic_model_creator() generates Pydantic models from Tortoise models. In v1.0, internal validator logic was cleaned up — custom PydanticMeta overrides may behave differently.

fix

Test pydantic_model_creator() output after upgrading to v1.0.

affects: >= 1.0

gotchaDB-specific drivers must be installed separately. 'pip install tortoise-orm' alone raises ImproperlyConfigured when connecting to PostgreSQL or MySQL.

fix

pip install 'tortoise-orm[asyncpg]' for PostgreSQL, 'tortoise-orm[asyncmy]' for MySQL, 'tortoise-orm[aiosqlite]' for SQLite.

affects: all

breakingDatabase server is unreachable or connection refused. The application is configured to connect to a database (e.g., PostgreSQL on port 5432), but the server is not running or is not accessible at the specified host/port (e.g., 127.0.0.1:5432).

fix

Ensure your database server (e.g., PostgreSQL) is running and accessible from the application's environment on the configured host and port. Verify database server logs, firewall rules, and the connection string (TORTOISE_CONFIG) used by Tortoise-ORM.

affects: all

Upgrade

Version history

1.1.8latest on PyPI · released Aug 10, 2026

Audit

Dependencies

asyncpgoptionalRequired for PostgreSQL. Install via tortoise-orm[asyncpg].

aiosqliteoptionalRequired for SQLite async. Install via tortoise-orm[aiosqlite].

asyncmyoptionalRequired for MySQL. Install via tortoise-orm[asyncmy].

Agent activity

58 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tortoise/tortoise-orm ↗

packagehttps://pypi.org/project/tortoise-orm/ ↗

homepagehttps://tortoise-orm.readthedocs.io ↗

docshttps://tortoise.github.io ↗