Install SQLModel in Python Guide

SQLModel is a powerful library for Python. It combines SQLAlchemy and Pydantic. This makes database work easy and clean.

You get type validation and database interaction in one tool. It is great for building APIs with FastAPI. This guide shows you how to install SQLModel step by step.

What is SQLModel?

SQLModel is a Python library for interacting with SQL databases. It uses Python type annotations. This means less code and fewer errors.

It was created by the author of FastAPI. It is designed for modern Python development. You can define your database tables as Python classes.

Each class attribute becomes a database column. The library handles the SQL for you. This is perfect for beginners who want clean code.

Prerequisites

Before installing SQLModel, you need Python installed. Check your Python version. Open your terminal or command prompt.

Type this command to check:

python --version

You need Python 3.7 or newer. If you don't have Python, download it from python.org. Make sure to check "Add Python to PATH" during installation.

You also need pip installed. Pip is the package installer for Python. It usually comes with Python.

Check pip version:

pip --version

How to Install SQLModel

The easiest way to install SQLModel is with pip. Open your terminal. Run this single command.

pip install sqlmodel

This command downloads SQLModel and its dependencies. It installs SQLAlchemy and Pydantic automatically. The process is fast and simple.

You will see output like this:

Collecting sqlmodel
  Downloading sqlmodel-0.0.22-py3-none-any.whl (47 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 47.3/47.3 kB 1.5 MB/s eta 0:00:00
Installing collected packages: sqlmodel
Successfully installed sqlmodel-0.0.22

That's it. You have installed SQLModel. Now you can start using it in your projects.

Install in a Virtual Environment

Always use a virtual environment for your Python projects. This keeps dependencies separate. It prevents conflicts between projects.

Create a virtual environment first:

python -m venv venv

Activate it. On Windows:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

Now install SQLModel inside the environment:

pip install sqlmodel

Your project stays clean. You can delete the environment anytime. This is best practice for all Python projects.

Verify the Installation

Check if SQLModel is installed correctly. Open a Python interpreter. Type this code:

import sqlmodel
print(sqlmodel.__version__)

You should see the version number. For example:

0.0.22

No errors mean success. You are ready to build database models.

First SQLModel Example

Let's create a simple model. This shows how SQLModel works. Create a file called models.py.

# Import SQLModel
from sqlmodel import SQLModel, Field, create_engine

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

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

# Create all tables
SQLModel.metadata.create_all(engine)

print("Database created successfully!")

Run this script:

python models.py

Output:

Database created successfully!

You just created a SQLite database. The Hero table has four columns. SQLModel uses Python types to define them.

Install Specific Version

Sometimes you need a specific version. Maybe for compatibility. Use the version number with pip.

pip install sqlmodel==0.0.21

Check available versions on PyPI. Visit pypi.org/project/sqlmodel. Choose the version that fits your project.

Install with Database Driver

SQLModel works with different databases. By default, it uses SQLite. For PostgreSQL or MySQL, install a driver.

For PostgreSQL:

pip install sqlmodel psycopg2-binary

For MySQL:

pip install sqlmodel pymysql

Then change the connection string. SQLModel uses SQLAlchemy under the hood. So any SQLAlchemy driver works.

Common Installation Errors

You might see errors. Don't worry. Here are fixes for common problems.

Error: "pip is not recognized". This means pip is not in your PATH. Reinstall Python and check "Add to PATH". Or use python -m pip install sqlmodel.

Error: "Permission denied". On macOS or Linux, use sudo before the command. But better to use a virtual environment.

Error: "No matching distribution found". Your Python version might be too old. Upgrade to Python 3.7 or newer.

Upgrade SQLModel

New versions come with fixes and features. Upgrade when needed. Use this command:

pip install --upgrade sqlmodel

Check your current version first. Then compare with the latest on PyPI.

Uninstall SQLModel

Need to remove it? Use pip uninstall.

pip uninstall sqlmodel

Type y to confirm. This removes the library but not your database files.

Conclusion

Installing SQLModel is simple. Use pip in a virtual environment. Verify the installation with a quick import test.

Start with SQLite for learning. Expand to other databases later. SQLModel makes database code clean and type-safe.

You now have the tool to build robust data models. Combine it with FastAPI for web applications. Happy coding.