Python

This page covers the requirements and internals of deploying Python content to ricochet.

Project requirements

Every Python deployment requires 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 satisfy the requires-python constraint recorded in uv.lock.

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

Python content items can be deployed 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 is run directly; it 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. |

How ricochet runs Python content

uv binary resolution

Ricochet resolves the uv binary in the following order:

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

Python version discovery

Ricochet discovers Python installations on the host machine. We recommend installing Python versions via uv for the best experience:

uv python install 3.12

When a deployment is received, ricochet matches the version in .python-version against available installations and selects the closest match.

Environment restoration

When a bundle is deployed, ricochet restores the Python environment using:

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

The --frozen flag ensures the lockfile is used exactly as provided — no resolution or updates occur on the server. The --no-python-downloads flag prevents uv from downloading Python versions at deploy time; they must already be installed on the host.

uv cache

Resolved packages are cached at $RICOCHET_HOME/.cache/uv. This directory is created automatically during the first Python deployment. The cache is shared across all Python content items on the server.