# Troubleshooting Python Deploys

If your Python app fails to deploy on Render, see below for common causes and resolutions.

> For more general-purpose troubleshooting tips, see [Troubleshooting Your Deploy](troubleshooting-deploys).

## Incorrect runtime

While creating a Render service, you select the [runtime](language-support) that corresponds to your language:

[image: Selecting the Python native runtime]

If you select an incorrect runtime, your service's environment lacks Python-specific tools and libraries that you might need (such as Poetry).

### Example symptoms

If you encounter any of the following issues, your service might be using an incorrect runtime:

- Setting the `PYTHON_VERSION` environment variable does _not_ change your service's Python version.
- Your [deploy logs](logging#logs-for-an-individual-deploy-or-job) include messages such as:
  - `bash: poetry: command not found` — Poetry and other Python tools are included only in the Python runtime.

### Steps to resolve

1. In the [Render Dashboard](https://dashboard.render.com), open your service's settings and confirm at the top of the page that the runtime is *Python 3* (or *Docker* if your Python app is built from a Dockerfile):

   [image: The Python 3 runtime label for a service in the Render Dashboard]

2. If you're using an incorrect runtime, the fastest fix is usually to create a _new_ service with the correct runtime.
   - You can also change an existing service's runtime via Render Blueprints or the API. [See details](native-runtimes#changing-a-services-runtime).

## Incompatible Python version

You can set a Python version for your service via the `PYTHON_VERSION` environment variable:

[image: Setting the PYTHON_VERSION environment variable]

If you don't do this, Render uses its [default version](python-version).

It's possible that your app uses a language feature or a dependency that requires a different version of Python from what your service currently uses.

### Example symptoms

If you encounter any of the following issues, your service's Python version might be incompatible with your app:

- Your [deploy logs](logging#logs-for-an-individual-deploy-or-job) include messages such as:
  - `Current Python version (3.11.10) is not allowed by the project (^3.12).`
  - `SyntaxError: invalid syntax.` — This often means your code uses syntax that was introduced in a newer version of Python than what your service uses.

### Steps to resolve

1. Verify which version(s) of Python your app is compatible with:
   - If your project uses a `pyproject.toml` file, the `python` key specifies Python version compatibility.
   - If your app works on your local machine, check which Python version you're running locally. (If you're using a virtual environment, make sure to check the Python version for that environment.)
2. In the [Render Dashboard](https://dashboard.render.com), go to your service's *Environment* page and set a compatible Python version via the `PYTHON_VERSION` [environment variable](configure-environment-variables):

   [image: Setting the PYTHON_VERSION environment variable]

## Missing dependencies

If your app uses third-party libraries (such as packages available on [PyPI](https://pypi.org/)), you need to install those dependencies in your service's runtime.

### Example symptoms

If you encounter any of the following issues, your service might be missing third-party dependencies required by your app:

- Your app crashes deterministically. It might crash on startup, or when you trigger a specific code path.
- Your [deploy logs](logging#logs-for-an-individual-deploy-or-job) include messages such as:
  - `ModuleNotFoundError`
  - `ImportError`

### Steps to resolve

1. Specify your app's Python dependencies in a dependency file. Add this file to your codebase and commit it via version control.

   Exactly how you do this differs based on which package management tool you're using. For example:

   - If you're using [pip](https://packaging.python.org/en/latest/key_projects/#pip), commit a [`requirements.txt`](https://pip.pypa.io/en/stable/user_guide/#requirements-files) file. You can use [`pip freeze`](https://pip.pypa.io/en/stable/cli/pip_freeze/#pip-freeze) to generate this file.
   - If you're using [Poetry](https://python-poetry.org/), commit both your project's [`pyproject.toml`](https://python-poetry.org/docs/basic-usage/#project-setup) file and the autogenerated [`poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock) file.

2. In the [Render Dashboard](https://dashboard.render.com), go to your service's *Settings* page and ensure that you've configured the *Build Command* to install your Python dependencies.

   The command you use depends on your package management tool:

   - If you're using [pip](https://packaging.python.org/en/latest/key_projects/#pip), use `pip install -r requirements.txt`.
   - If you're using [Poetry](https://python-poetry.org/), use `poetry install`.
   - If you're using [uv](https://docs.astral.sh/uv/), use `uv sync`.
     - To use `uv`, a `uv.lock` file must be present in your service's root directory. [Learn more](uv-version).

   Your build command can run the corresponding command directly (possibly in conjunction with other commands relevant to your build step), or it can execute a script in your repo that includes the command. [Learn more about the build command](/deploys#build-command).