Install Tortoise-ORM in Python

Tortoise-ORM is an easy-to-use async ORM for Python. It works well with databases like PostgreSQL, MySQL, and SQLite. This guide shows you how to install and set it up quickly.

What is Tortoise-ORM?

Tortoise-ORM is a modern async ORM inspired by Django ORM. It uses Python's async/await syntax. This makes it perfect for fast web apps and async tasks.

It supports multiple databases. You can use it with FastAPI, AIOHTTP, or any async framework.

Prerequisites

You need Python 3.8 or newer. Also, have pip installed. A virtual environment is recommended for clean projects.

Open your terminal or command prompt before starting.

Install Tortoise-ORM

Step 1: Create a Virtual Environment

First, create a virtual environment to keep dependencies isolated.

# On Windows
python -m venv venv
venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

Step 2: Install Tortoise-ORM with pip

Run this command to install the core package.

pip install tortoise-orm

This installs the base ORM. For database support, add the correct driver.

Step 3: Install Database Driver

Choose your database and install its driver. Common options include:

• For SQLite: pip install aiosqlite
• For PostgreSQL: pip install asyncpg
• For MySQL: pip install asyncmy

Example for SQLite:

pip install aiosqlite

Verify Installation

Check if Tortoise-ORM installed correctly.

import tortoise
print(tortoise.__version__)

Run the script. You should see a version number.

0.20.0

No errors mean success.

Basic Setup Example

Create a file named main.py. Add this code to test the ORM.

import asyncio
from tortoise import Tortoise, fields, run_async
from tortoise.models import Model

# Define a simple model
class User(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50)
    email = fields.CharField(max_length=100)

    def __str__(self):
        return self.name

async def init():
    # Connect to SQLite database
    await Tortoise.init(
        db_url='sqlite://db.sqlite3',
        modules={'models': ['__main__']}
    )
    # Generate schema
    await Tortoise.generate_schemas()

    # Create a user
    user = await User.create(name='Alice', email='[email protected]')
    print(f'Created user: {user}')

    # Fetch all users
    users = await User.all()
    print(f'All users: {users}')

    # Close connection
    await Tortoise.close_connections()

# Run the async function
run_async(init())

Run the script:

python main.py

Expected output:

Created user: Alice
All users: [<User: Alice>]

This confirms Tortoise-ORM works.

Install with Additional Features

You can install extra packages for serialization or pydantic support.

pip install tortoise-orm[accel]

The accel extra adds C extensions for better performance.

Common Installation Issues

If you see ModuleNotFoundError, check the driver. For example, missing asyncpg for PostgreSQL.

Solution: Install the required driver with pip.

Another issue is Python version. Tortoise-ORM needs Python 3.8+. Upgrade if needed.

Conclusion

Installing Tortoise-ORM in Python is simple. Use pip install tortoise-orm and add a database driver. Then create models and run async queries. This ORM makes async database work clean and fast. Start building your next async app today.