Guide · Open source

How to use SQLModel: define tables, save and query rows in Python

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

SQLModel is a Python library for working with SQL databases using Python classes with type annotations. Each class describes a database table and each attribute describes a column, so you write one model instead of separate SQLAlchemy and Pydantic models. This guide shows how to install it, define a model, save rows to a SQLite database and query them.

SQLModelfastapi/sqlmodel · ★ 18.5k · MIT Install options & downloads

Quick start

1Install SQLModel. Run uv add sqlmodel in your project, or install sqlmodel with pip inside a virtual environment.
2Define a model. Create a class that inherits from SQLModel with table=True and annotate each column as an attribute.
3Create an engine. Call create_engine with a database URL such as sqlite:///database.db.
4Create the tables. Run SQLModel.metadata.create_all(engine) to create the tables defined by your models.
5Save rows. Create model instances, add them to a Session and call commit.
6Query rows. Use select with where and session.exec to read matching rows.

Install SQLModel

SQLModel needs a recent, currently supported version of Python. It depends on Pydantic and SQLAlchemy, which are installed automatically with it.

If you use uv, add SQLModel to your project from the project folder. If you prefer pip, install sqlmodel inside a virtual environment; the project's installation guide covers those steps.

uv add sqlmodel

Define a table as a Python class

Imagine a SQL table called hero with the columns id, name, secret_name and age. In SQLModel you write a class that inherits from SQLModel and passes table=True. The class is the table, and each annotated attribute is a column.

The id field is marked as the primary key, and age is optional because it defaults to None.

Set table=True on the class to make it a database table.
Use Field(default=None, primary_key=True) for an auto-assigned primary key.
Annotate optional values such as int | None.

from sqlmodel import Field, SQLModel


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None

Create rows and save them to SQLite

Each row is an instance of the model. To write rows, create an engine with create_engine, create the tables with SQLModel.metadata.create_all, then add the objects to a Session and commit.

The example below uses a SQLite file called database.db. The source notes that this saves a SQLite database containing the three heroes.

create_engine sets up the connection to the database.
SQLModel.metadata.create_all(engine) creates the tables.
session.commit() saves the added rows.

from sqlmodel import Field, Session, SQLModel, create_engine


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None


hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)


engine = create_engine("sqlite:///database.db")


SQLModel.metadata.create_all(engine)

with Session(engine) as session:
    session.add(hero_1)
    session.add(hero_2)
    session.add(hero_3)
    session.commit()

Query rows with select

To read data, build a statement with select and a where condition on the model's attributes, then run it with session.exec. Calling first() returns the first matching row.

Filter with Hero.name == "Spider-Boy" inside where().
Use session.exec(statement).first() to get one result.

from sqlmodel import Field, Session, SQLModel, create_engine, select


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None


engine = create_engine("sqlite:///database.db")

with Session(engine) as session:
    statement = select(Hero).where(Hero.name == "Spider-Boy")
    hero = session.exec(statement).first()
    print(hero)

Use SQLModel with FastAPI and SQLAlchemy

SQLModel is designed to work with FastAPI. Because a model is both a SQLAlchemy model and a Pydantic model, you can reuse it in FastAPI applications and inherit from it to define data models without duplicating code.

Because it is built on SQLAlchemy, you can combine SQLModel models with other SQLAlchemy models, and existing SQLAlchemy applications can be migrated gradually.

What people use it for

Building a FastAPI application that stores data in a SQL database.
Reducing duplicated SQLAlchemy and Pydantic model code in a Python project.
Prototyping with a SQLite file and later moving to another SQL database.
Getting editor autocompletion and type hints when querying data in Python.

Frequently asked questions

How do I install SQLModel?

Install uv, then run uv add sqlmodel in your project. If you prefer pip, install sqlmodel inside a virtual environment. SQLModel needs a recent, currently supported version of Python.

Is SQLModel free to use?

SQLModel is licensed under the MIT license, as stated in the project's README. The license file is linked from the repository.

What does SQLModel require?

It requires a recent, currently supported version of Python. It is built on Pydantic and SQLAlchemy, and those are installed automatically with SQLModel.

Is SQLModel different from SQLAlchemy?

SQLModel is built on top of SQLAlchemy and Pydantic. A SQLModel class is also a SQLAlchemy model, so you keep access to SQLAlchemy's power, but you write one class instead of separate SQLAlchemy and Pydantic models.

Can I use SQLModel without knowing SQL?

The README says SQLModel's own docs focus on the library and point to separate documentation for databases and SQL basics. If you are new to databases, learn the basics first.

Does SQLModel only work with FastAPI?

No, but it is designed to work well with FastAPI. The library is Python-only and is also compatible with Pydantic and SQLAlchemy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

SQLModel suits Python developers building FastAPI apps who want one model for both database tables and validated data, especially if they start with SQLite. If you are new to SQL, need full low-level control of SQLAlchemy, or work outside Python, consider learning SQLAlchemy directly or another option such as Peewee or Tortoise ORM.

Install options & downloads