Installation

This is the v1.0 documentation, for a release that is still in development. The API it describes is not on PyPI and can still change.

Reading about the version you have installed? Switch to v0.x.

Installation

One command puts the framework in place: routing, validation, dependency injection, the response builder, and the middleware stack. The heavier pieces (the ORM, JWT, caching, Redis) are optional extras you add when the product needs them, so the dependency tree stays proportional to what you build.

Requirements

• Python 3.10 or newer
• Basic familiarity with async / await

python --version

Nothing else. These guides are written against uv, but every command below has a Poetry and a venv plus pip equivalent, so none of it depends on having uv. To install it:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Create a project

uv (recommended)

uv init my-sillo-app
cd my-sillo-app
uv add sillo-framework

You get a pyproject.toml, a .venv, and an exact uv.lock.

Poetry

poetry new my-sillo-app --src
cd my-sillo-app
poetry add sillo-framework

You get a pyproject.toml and a poetry.lock. The environment is created on the first poetry add.

venv + pip

mkdir my-sillo-app && cd my-sillo-app
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install sillo-framework

venv and pip ship with Python, so this needs nothing installed first. Nothing records what you installed, so pin it yourself with pip freeze > requirements.txt.

Confirm it worked:

uv run sillo --version          # uv
poetry run sillo --version      # Poetry
sillo --version                 # venv + pip, with the environment activated

Prefixing commands

Every later example is written bare, as sillo db:migrate. Prefix it with uv run under uv, or poetry run under Poetry. With an activated venv, type it as written.

Add a development server

Sillo is ASGI-based, so it needs a server. uvicorn is the usual choice:

uv (recommended)

uv add uvicorn

Poetry

poetry add uvicorn

venv + pip

pip install uvicorn

Create your first app

Create main.py:

from sillo import SilloApp, HttpContext

app = SilloApp()


@app.get("/")
async def home(ctx: HttpContext):
    return {"message": "Hello from Sillo"}

Run it:

uvicorn main:app --reload

Open:

http://127.0.0.1:8000

You should see:

{"message": "Hello from Sillo"}

Install optional feature groups

Sillo ships optional extras for integrations that need additional dependencies. Add them only when your project needs them.

uv (recommended)

uv add "sillo-framework[mail]"
uv add "sillo-framework[jwt]"
uv add "sillo-framework[cache]"
uv add "sillo-framework[record]"
uv add sillo-graphql
uv add "sillo-framework[all]"      # everything

Poetry

poetry add "sillo-framework[mail]"
poetry add "sillo-framework[jwt]"
poetry add "sillo-framework[cache]"
poetry add "sillo-framework[record]"
poetry add sillo-graphql
poetry add "sillo-framework[all]"     # everything

venv + pip

pip install "sillo-framework[mail]"
pip install "sillo-framework[jwt]"
pip install "sillo-framework[cache]"
pip install "sillo-framework[record]"
pip install sillo-graphql
pip install "sillo-framework[all]"    # everything

Existing projects

Install it into whatever the project already uses:

uv add sillo-framework            # uv
poetry add sillo-framework        # Poetry
pip install sillo-framework       # venv + pip

Sillo does not care which. It is an ordinary package with a standard pyproject.toml, so it installs the same way anything else does. In a directory that has no pyproject.toml yet, run uv init or poetry init first.

Upgrading from 0.0.1a15 or earlier

The application class was renamed from silloApp to SilloApp. Classes in Python are CapWords, and the old spelling made app = silloApp() read like a function call at every entry point.

The migration is one find-and-replace:

from sillo import SilloApp

app = SilloApp(title="Projects API")

Nothing else in the constructor changed: every argument, and every method on the returned application, is the same. The only other visible difference is that str(app) now reads <SilloApp: title>, which matters if you assert on dev-server output or log lines.

Why uv is recommended

Recommended, not required, and recommended strongly. It resolves and installs an order of magnitude faster than pip, produces a lockfile without a separate tool, installs the Python interpreter itself when you need a version you do not have, and runs commands inside the environment without an activate step to forget.

Poetry gives you the lockfile and the dependency groups but not the speed or the interpreter management. venv and pip give you neither, in exchange for needing nothing installed.

If your team already has a workflow, keep it. Nothing in Sillo reads a lockfile or shells out to a package manager, so the choice is yours alone.

Next step

Continue with the Introduction if you want the framework overview, or go directly to Routing to start building endpoints.