Installation

In this tutorial, you will install Semolina and verify it is working. By the end, you will be ready to write your first query.

Prerequisites: Python 3.11 or later.

Install the package

pip install semolina

Tip

Use a virtual environment

Always install packages into an isolated virtual environment rather than your system Python:

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows
pip install semolina

uv add semolina

Install a backend extra

To connect to a real warehouse, install the extra for your backend:

pip install "semolina[snowflake]"
# or
uv add "semolina[snowflake]"

Installs adbc-poolhouse[snowflake] and pyarrow alongside Semolina.

pip install "semolina[databricks]"
# or
uv add "semolina[databricks]"

Installs databricks-sql-connector[pyarrow] and pyarrow alongside Semolina. The ADBC Databricks driver is not on PyPI and no extra can fetch it, so add it with the Foundry’s CLI:

uv tool install dbc     # or: pipx install dbc
dbc install "databricks>=0.2.0"

Semolina needs driver version 0.2.0 or later. See Databricks for why, how the driver is found, and what failure looks like when it is missing.

pip install "semolina[duckdb]"
# or
uv add "semolina[duckdb]"

Installs duckdb and pyarrow, for the tutorials, for tests, or as a backend in its own right.

pip install "semolina[snowflake,databricks]"
# or
uv add "semolina[snowflake,databricks]"

To follow the tutorials without a real warehouse, install semolina[duckdb]. Your first query builds the local DuckDB database the rest of them use.

Optional: the semolina command

The semolina command generates model classes from existing warehouse views (semolina codegen) and result classes from queries (semolina codegen-dto). Its dependencies are not part of a plain install, because a service that only runs queries does not need them. Add the cli extra where you run the command:

pip install "semolina[cli]"
# or
uv add "semolina[cli]"

Without it, running semolina prints that install line and exits with code 2.

Optional: formatted codegen output

Add the codegen-lint extra and codegen formats the generated source with ruff before printing. It includes the cli extra:

pip install "semolina[codegen-lint]"
# or
uv add "semolina[codegen-lint]"

Codegen works without it, just without the formatting pass.

Optional: async support

If you query from an async web framework, add the async extra. It brings in adbc-poolhouse’s async stack, which is what create_async_engine() and aexecute() run on:

pip install "semolina[async]"
# or
uv add "semolina[async]"

Combine it with your backend extra in one install:

pip install "semolina[snowflake,async]"
# or
uv add "semolina[snowflake,async]"

A plain pip install semolina picks up no part of this. The async stack brings an anyio dependency with it, and Semolina keeps that out of a base install: nothing is imported until you call an async entry point. The all extra includes async.

The extra requires adbc-poolhouse[async]>=1.6.4. Earlier releases could deadlock on a cancelled query, or stall every query when more ran at once than the pool holds.

Optional: dataframes and typed results

Four extras cover what you can turn a result into. A plain pip install semolina brings none of them.

Typed objects. arrowmodel is the one to install if you want into() and iter_into(), which convert a result into Pydantic instances:

pip install "semolina[arrowmodel]"
# or
uv add "semolina[arrowmodel]"

It brings pyarrow along, so this single command is enough. See How to map results into Pydantic models with .into().

Dataframes. semolina[pandas] covers fetch_df(), and semolina[polars] covers fetch_polars():

pip install "semolina[pandas]"
pip install "semolina[polars]"

Each command is enough on its own. semolina[pandas] pulls pyarrow in for you, because ADBC builds a pandas frame through a PyArrow reader. semolina[polars] does not, because ADBC hands polars the raw Arrow stream instead, so it stays the smaller install. See Fetch the whole result for both methods.

Arrow. pyarrow covers fetch_arrow_table(), fetch_record_batch() and the column types in cursor.description:

pip install "semolina[pyarrow]"

Most readers never install it directly. Every backend extra brings it, because ADBC reads every row through a PyArrow reader, and so do semolina[arrowmodel] and semolina[pandas].

The all extra covers all four, alongside async and every backend.

Each extra sets a minimum version rather than a pin, so a later compatible release can land in your environment without waiting for a Semolina release: pyarrow>=17.0.0, polars>=1.0.0, pandas>=2.0.0, arrowmodel>=1.0.0.

If you call one of these methods without its extra installed, Semolina raises SemolinaMissingDependencyError and names the package to install.

Verify the installation

Run this in your terminal:

python -c "import semolina; print(semolina.__version__)"

You should see the version you installed:

0.7.0

If the import fails, double-check that you are in the right virtual environment.

If you installed the async extra, check that its dependencies resolved too:

python -c "from adbc_poolhouse import create_async_pool; print('async support ready')"

You should see:

async support ready

An ImportError here means the extra is not installed – the async stack is resolved lazily, so import semolina succeeds either way and does not tell you.

Next steps

Your installation is ready. Move on to writing your first query:

Your first query

See also