Skip to content
ricochet

Python

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

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.

[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

You can deploy Python content items as apps or tasks.

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.
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.

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

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

Terminal window
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.

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

Terminal window
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.

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.