The Python platform uses python 3.14.2 by default (based on Ubuntu 24.04) and gets your dependencies with pip, either by Pipfile.lock, requirements.txt or setup.py.

You can define which python version you want using one of the following methods (in priority order):

1. Pipfile.lock - if present, the python_version field in _meta.requires will be used (highest priority to avoid pipenv conflicts)
2. poetry.lock - if present, the python-versions field in [metadata] will be used
3. uv.lock - if present, the requires-python field will be used
4. PYTHON_VERSION environment variable - set via tsuru env-set
5. .python-version file - a file in your project root containing the version number
6. Default version - if none of the above are specified, the latest Python 3.x version will be used

Always use full version numbers (e.g., 3.14.2) or partial versions (e.g., 3.14 for latest 3.14.x, or 3.14.x).

Example .python-version file:

3.14.2

Python versions are automatically fetched from python.org during platform installation, ensuring the latest releases are always available. The platform supports all actively maintained Python 3.x versions.

To see the exact versions available in your platform installation, check the generated versions file at /var/lib/tsuru/python/latest_versions.sh on the platform image.

By default, the latest pip version will be installed. If you want to use a specific version, set a PYTHON_PIP_VERSION environment variable. It accepts a specific version (PYTHON_PIP_VERSION=7.1.2) or a requirement specifier (PYTHON_PIP_VERSION="<10").

If you just run a tsuru app deploy of your code, tsuru will try to download all of your depencies using requirements.txt or setup script. You can customize this behavior, see the next section for more details.

There are several ways to list the applications dependencies: poetry.lock, uv.lock, Pipfile.lock, requirements.txt or setup.py. The priority order is: poetry.lock -> uv.lock -> Pipfile.lock -> requirements.txt -> setup.py. The file should be in the root of deploy files.

If you have a poetry.lock file (generated by Poetry), tsuru will use poetry to install the dependencies of your application. Poetry will be installed automatically during deployment.

You can optionally specify a Poetry version by setting the PYTHON_POETRY_VERSION environment variable (e.g., PYTHON_POETRY_VERSION=1.8.0 or PYTHON_POETRY_VERSION=">=1.8,<2.0").

Example pyproject.toml:

[tool.poetry]
name = "my-app"
version = "0.1.0"
description = ""

[tool.poetry.dependencies]
python = "^3.14"
Flask = "^3.0.0"
gunicorn = "^21.2.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

If you have a uv.lock file (generated by uv), tsuru will use uv to install the dependencies of your application. uv will be installed automatically during deployment.

You can optionally specify a uv version by setting the PYTHON_UV_VERSION environment variable (e.g., PYTHON_UV_VERSION=0.7.0 or PYTHON_UV_VERSION=">=0.6,<1.0").

uv natively supports UV_INDEX_URL and UV_EXTRA_INDEX_URL environment variables for custom package indexes.

Example pyproject.toml:

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "Flask>=3.0.0",
    "gunicorn>=21.2.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

If you have a Pipfile.lock file, tsuru will use pipenv to install the dependencies of your application.

You can define a file called requirements.txt that list all pip dependencies of your application, each line represents one dependency, here's an example:

$ cat requirements.txt

Flask==0.10.1
gunicorn==19.3.0

You can also define the setup script to list your dependencies, here's an example:

$ cat setup.py

from setuptools import setup, find_packages
setup(
    name="app-name",
    packages=find_packages(),
    description="example",
    include_package_data=True,
    install_requires=[
        "Flask==0.10.1",
        "gunicorn==19.3.0",
    ],
)

After invoking tsuru app-deploy, tsuru will receive your code and tell the platform to install all the dependencies using poetry install, uv sync, pipenv install --system --deploy, pip install -r requirements.txt or pip install -e ./.