How to Install tortoise-orm in Python
Easy async ORM for python, built with relations in mind
pip install tortoise-orm
What is tortoise-orm?
Easy async ORM for python, built with relations in mind
Tortoise ORM is an easy-to-use `` ORM (Object Relational Mapper) inspired by Django.
Tortoise ORM supports CPython 3.10 and later for SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.
Tortoise ORM was built to provide a lightweight, async-native Object-Relational Mapper for Python with a familiar Django-like API.
Quick Start
Minimal example to get started with tortoise-orm:
import tortoise_orm
print(tortoise_orm.__version__)Installation
pip (standard)
pip install tortoise-ormVirtual environment (recommended)
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install tortoise-ormpip3
pip3 install tortoise-ormconda
conda install -c conda-forge tortoise-ormPoetry
poetry add tortoise-ormDependencies
Installing tortoise-orm will also install these packages:
Verify the Installation
After installing, confirm the package is available:
python -c "import tortoise_orm; print(tortoise_orm.__version__)"If this prints a version number, installation succeeded. If you see a ModuleNotFoundError, see the errors section below.
Installation Errors
Common errors when installing tortoise-orm with pip.
ModuleNotFoundError: No module named 'tortoise_orm'
Cause: The package is not installed in the current Python environment.
Fix: Run pip install tortoise-orm. If using a virtual environment, ensure it is activated first.
ModuleNotFoundError: No module named 'tortoise_orm' (installed but still failing)
Cause: pip installed the package into a different Python than the one running your script.
Fix: Use python -m pip install tortoise-orm to install into the interpreter you are running.
ImportError: cannot import name 'X' from 'tortoise_orm'
Cause: The function or class does not exist in the installed version.
Fix: Check the version with pip show tortoise-orm and upgrade with pip install --upgrade tortoise-orm.
pip: command not found
Cause: pip is not in PATH or Python was not added to PATH during installation.
Fix: Try python -m pip install tortoise-orm. On macOS/Linux try pip3.
PermissionError: [Errno 13] Permission denied
Cause: No write access to the system Python package directory.
Fix: Use a virtual environment, or add --user: pip install --user tortoise-orm
SSL: CERTIFICATE_VERIFY_FAILED
Cause: pip cannot verify PyPI's SSL certificate — common behind corporate proxies.
Fix: Try: pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org tortoise-orm
RuntimeError: This event loop is already running
Cause: Calling <code>asyncio.run()</code> inside Jupyter or another already-running event loop.
Fix: In Jupyter, use await directly. Or install nest_asyncio and call nest_asyncio.apply().
Recent Releases
| Version | Released |
|---|---|
1.1.7 latest |
2026-03-21 |
1.1.6 |
2026-03-05 |
1.1.5 |
2026-02-19 |
1.1.4 |
2026-02-17 |
1.1.3 |
2026-02-16 |
Manage tortoise-orm
Upgrade to latest version
pip install --upgrade tortoise-ormInstall a specific version
pip install tortoise-orm==1.1.7Uninstall
pip uninstall tortoise-ormCheck what is installed
pip show tortoise-orm