Python

This page covers what you need to deploy Python content to ricochet and how ricochet runs it.

Project requirements

Every Python deployment needs two files in the project root:

File	Purpose
.python-version	Specifies the target Python version (e.g. 3.12 or 3.12.7).
uv.lock	The lockfile generated by uv lock.

The version in .python-version must match the requires-python range in uv.lock.

A Jupyter notebook also needs nbconvert and ipykernel in uv.lock:

uv add --dev nbconvert ipykernel

Note

uv.lock is the only supported dependency lockfile for Python. Other tools such as pip, poetry, and conda are not supported.

Example _ricochet.toml

[content]
name = "My FastAPI App"
entrypoint = "app.py"
access_type = "external"
content_type = "fast-api"

[language]
name = "python"
packages = "uv.lock"

[serve]
min_instances = 0
max_instances = 5

Supported content types

You can deploy Python content items as apps or tasks.

Apps

Content Type	Description
fast-api	An API developed using FastAPI. Launched with uvicorn.
flask	A web app or API developed using Flask.
streamlit	A data app developed using Streamlit.
dash	A data app developed using Dash.
shiny-py	A web app developed using Shiny for Python.
python-service	A generic Python web app or API. The entrypoint script runs directly and must bind to PORT from the environment.

Tasks

Content Type	Description
python	A Python script with the extension .py.
quarto-py	A Quarto document using a Python runtime. Can be served as a static site.
jupyter	A Jupyter notebook with the extension .ipynb. Always served as a static site.

How ricochet runs Python content

uv binary resolution

Ricochet looks for the uv binary in this order:

1. Vendored: $RICOCHET_HOME/vendor/py/uv (installed with the ricochet package)
2. System PATH: uv on PATH, if the vendored binary is not present

Python version discovery

Ricochet finds the Python versions installed on the host machine. For the best results, install Python versions with uv:

uv python install 3.12

When ricochet gets a deployment, it compares the version in .python-version with the installed versions and picks the closest match.

Environment restoration

When you deploy a bundle, ricochet restores the Python environment with this command:

uv sync --python <matched-python> --cache-dir $RICOCHET_HOME/.cache/uv --no-python-downloads --frozen

The --frozen flag makes uv use the lockfile exactly as you provide it. The server does not resolve or update any packages. The --no-python-downloads flag stops uv from downloading Python versions at deploy time. The Python version must already be installed on the host.

uv cache

Ricochet caches resolved packages in $RICOCHET_HOME/.cache/uv. Ricochet creates this directory during the first Python deployment. All Python content items on the server share the cache.