---
id: aerich
version: "0.10.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# aerich — A database migrations tool for Tortoise ORM.

License: permissive · Maintenance: active · Downloads: 274.3K/mo

## What it is and what it does

Aerich is a migration tool designed specifically for TortoiseORM, an async Python ORM. It provides a command-line interface and programmatic API to generate, version, and apply database schema changes. The tool detects model changes, generates migration files with timestamped versions, and can upgrade or downgrade the database schema. It also includes an inspectdb command to reverse-engineer existing database tables into TortoiseORM model definitions.

The package depends on tortoise-orm (the ORM it targets), dictdiffer (for comparing model states), asyncclick (for CLI), and anyio (for async compatibility). It's actively maintained and supports modern Python versions (3.10 through 3.14). However, the project's own documentation warns that tortoise-orm>=1.0.0 includes built-in migration support as an alternative, so users should verify whether Aerich or the built-in solution better fits their needs.

Use it for:

- Track and apply schema changes in TortoiseORM projects without manually writing SQL or managing version state.
- Reverse-engineer existing MySQL, PostgreSQL, or SQLite databases into TortoiseORM model definitions via inspectdb.
- Manage multiple database connections and per-app migration directories in complex projects.
- Programmatically run migrations within an application using the Command class instead of CLI.
- Roll back database changes to a previous version when a migration causes issues.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Aerich is a database migration tool for TortoiseORM that generates, tracks, and applies schema changes through a CLI and programmatic interface, similar to Alembic for SQLAlchemy.

Yes, if you are using TortoiseORM and need structured database migrations. The package is actively maintained, has no known vulnerabilities, and low install friction. However, check whether tortoise-orm>=1.0.0's built-in migration support meets your needs first, as the project itself recommends it as an alternative for newer versions.

## Install

pip install aerich
uv add aerich
poetry add aerich

## Installing aerich

Before you install: Installation is straightforward with low friction—a pure-Python wheel with four runtime dependencies. The package is actively maintained with a recent release and no known vulnerabilities, though the warning in its own documentation notes that tortoise-orm>=1.0.0 includes built-in migration support as an alternative.

License in practice: Licensed under Apache-2.0 (permissive), which allows free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install aerich

# In your project, add aerich.models to your Tortoise-ORM config:
TORTOISE_ORM = {
    "connections": {"default": "sqlite://:memory:"},
    "apps": {
        "models": {
            "models": ["myapp.models", "aerich.models"],
            "default_connection": "default",
        },
    },
}

# Then initialize and run migrations:
# aerich init -t myapp.config.TORTOISE_ORM
# aerich init-db
# aerich migrate --name add_column
# aerich upgrade

Requires Python >=3.10; tortoise-orm must be installed and configured with aerich.models included in the app config.

Verify before relying:

- Whether the built-in migration support in tortoise-orm>=1.0.0 fully replaces Aerich's functionality or if Aerich offers additional features.
- Support for databases beyond MySQL, PostgreSQL, and SQLite mentioned in the inspectdb command.
- Performance characteristics when handling large numbers of migration files.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 274.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tortoise orm migrations, database schema migration tool, async orm database versioning, tortoise-orm alembic alternative, python database migration cli, orm schema change management, tortoise migration generator, async-orm, schema-migration, cli-tool

[View on SkillFed](https://skillfed.io/packages/aerich) · [View on PyPI](https://pypi.org/project/aerich/)