> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Python

> Install, switch, and manage Python versions with uv

## Overview

uv can detect and use existing Python installations, but it can also install and manage Python versions for you. Python is automatically downloaded when needed — you don't need to install it first.

<Note>
  Python doesn't publish official distributable binaries. uv uses distributions from Astral's [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project. See [Python distributions](../concepts/python-versions.md#managed-python-distributions) for details.
</Note>

## Getting started

<Steps>
  <Step title="Install the latest Python">
    ```bash theme={null}
    uv python install
    ```

    This installs the latest stable Python version.
  </Step>

  <Step title="Use the installed Python">
    uv automatically uses installed versions:

    ```bash theme={null}
    python3.13
    ```

    By default, uv only installs versioned executables (e.g., `python3.13`).
  </Step>

  <Step title="Install default executables (experimental)">
    To also install `python` and `python3` executables:

    ```bash theme={null}
    uv python install --default
    ```
  </Step>
</Steps>

<Tip>
  See [installing Python executables](../concepts/python-versions.md#installing-python-executables) for more details.
</Tip>

## Installing specific versions

Install any Python version you need:

<CodeGroup>
  ```bash Specific minor version theme={null}
  uv python install 3.12
  ```

  ```bash Multiple versions theme={null}
  uv python install 3.11 3.12
  ```

  ```bash Alternative implementation theme={null}
  uv python install pypy@3.10
  ```

  ```bash Specific patch version theme={null}
  uv python install 3.11.8
  ```
</CodeGroup>

See [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation for all options.

## Viewing Python installations

List available and installed Python versions:

```bash theme={null}
uv python list
```

This shows:

* Installed versions (uv-managed and system)
* Available versions for download
* Version details (implementation, architecture)

<CodeGroup>
  ```bash List all available theme={null}
  uv python list
  ```

  ```bash List only installed theme={null}
  uv python list --only-installed
  ```

  ```bash List specific versions theme={null}
  uv python list 3.12
  ```
</CodeGroup>

See [`python list`](../concepts/python-versions.md#viewing-available-python-versions) for more details.

## Automatic Python downloads

Python is downloaded automatically when needed:

```bash theme={null}
# Downloads Python 3.12 if not installed
uvx python@3.12 -c "print('hello world')"
```

Even without a specific version request:

```bash theme={null}
# Downloads latest Python if none exists
uv venv
```

<Tip>
  Automatic downloads can be [easily disabled](../concepts/python-versions.md#disabling-automatic-python-downloads) if you want more control.
</Tip>

## Using existing Python versions

uv automatically discovers and uses system Python installations. No configuration needed!

### Force system Python

Prevent uv from using managed Python versions:

```bash theme={null}
uv venv --no-managed-python
```

See [Python version preference](../concepts/python-versions.md#requiring-or-disabling-managed-python-versions) for more details.

## Pinning Python versions

### In projects

The `.python-version` file pins the Python version for a project:

```bash theme={null}
echo "3.12" > .python-version
```

uv uses this file when creating virtual environments for the project.

### With pyenv compatibility

uv respects `.python-version` files created by `pyenv`:

```bash theme={null}
pyenv local 3.11.8
# Creates .python-version with "3.11.8"

uv venv
# Uses Python 3.11.8
```

## Upgrading Python versions

<Warning>
  Upgrading Python patch versions is in **preview** and may change.
</Warning>

Upgrade to the latest supported patch release:

<CodeGroup>
  ```bash Upgrade specific version theme={null}
  uv python upgrade 3.12
  ```

  ```bash Upgrade all versions theme={null}
  uv python upgrade
  ```
</CodeGroup>

This updates minor versions to their latest patch (e.g., 3.12.0 → 3.12.7).

See [`python upgrade`](../concepts/python-versions.md#upgrading-python-versions) documentation.

## Reinstalling Python

Reinstall uv-managed Python versions:

```bash theme={null}
uv python install --reinstall
```

This reinstalls all previously installed Python versions. Useful for:

* Fixing corrupted installations
* Getting improvements to Python distributions
* Resolving platform-specific issues

<Note>
  Improvements are constantly added to Python distributions, so reinstalling may resolve bugs even if the version number doesn't change.
</Note>

## Switching Python versions

### In projects

<Steps>
  <Step title="Check current version">
    ```bash theme={null}
    cat .python-version
    # 3.12
    ```
  </Step>

  <Step title="Change version">
    ```bash theme={null}
    echo "3.11" > .python-version
    ```
  </Step>

  <Step title="Recreate environment">
    ```bash theme={null}
    rm -rf .venv
    uv sync
    ```
  </Step>
</Steps>

### For specific commands

Use `--python` to override the Python version:

<CodeGroup>
  ```bash Run with specific version theme={null}
  uv run --python 3.10 main.py
  ```

  ```bash Create venv with version theme={null}
  uv venv --python 3.11
  ```

  ```bash Install tool with version theme={null}
  uv tool install --python 3.12 ruff
  ```
</CodeGroup>

## Working with multiple Python versions

### Install all versions you need

```bash theme={null}
uv python install 3.10 3.11 3.12 3.13
```

### Test across versions

```bash theme={null}
for version in 3.10 3.11 3.12; do
  echo "Testing with Python $version"
  uv run --python $version pytest
done
```

### Build with specific versions

```bash theme={null}
# Build wheels for multiple Python versions
uv build --python 3.11
uv build --python 3.12
```

## Complete workflow examples

### Setting up a new project

<Steps>
  <Step title="Install Python">
    ```bash theme={null}
    uv python install 3.12
    ```
  </Step>

  <Step title="Create project">
    ```bash theme={null}
    uv init my-project
    cd my-project
    ```
  </Step>

  <Step title="Verify Python version">
    ```bash theme={null}
    cat .python-version
    # 3.12
    ```
  </Step>

  <Step title="Start developing">
    ```bash theme={null}
    uv add httpx
    uv run main.py
    ```
  </Step>
</Steps>

### Migrating to a newer Python version

<Steps>
  <Step title="Install new Python">
    ```bash theme={null}
    uv python install 3.13
    ```
  </Step>

  <Step title="Update project">
    ```bash theme={null}
    echo "3.13" > .python-version
    ```
  </Step>

  <Step title="Update pyproject.toml">
    ```toml theme={null}
    [project]
    requires-python = ">=3.13"
    ```
  </Step>

  <Step title="Recreate environment">
    ```bash theme={null}
    rm -rf .venv
    uv sync
    ```
  </Step>

  <Step title="Test everything">
    ```bash theme={null}
    uv run pytest
    ```
  </Step>
</Steps>

### Working with PyPy

<Steps>
  <Step title="Install PyPy">
    ```bash theme={null}
    uv python install pypy@3.10
    ```
  </Step>

  <Step title="Create PyPy environment">
    ```bash theme={null}
    uv venv --python pypy@3.10
    ```
  </Step>

  <Step title="Use PyPy">
    ```bash theme={null}
    uv run --python pypy@3.10 main.py
    ```
  </Step>
</Steps>

## Best practices

<AccordionGroup>
  <Accordion title="Pin Python versions in projects">
    Always create a `.python-version` file in your project:

    ```bash theme={null}
    uv init my-project  # Automatically creates .python-version
    ```

    This ensures all team members use the same Python version.
  </Accordion>

  <Accordion title="Specify requires-python in pyproject.toml">
    Set minimum Python version in your project metadata:

    ```toml theme={null}
    [project]
    requires-python = ">=3.11"
    ```

    This documents compatibility and prevents installation on older Python.
  </Accordion>

  <Accordion title="Keep Python versions updated">
    Regularly upgrade to latest patch releases:

    ```bash theme={null}
    uv python upgrade
    ```

    Patch releases include security fixes and bug improvements.
  </Accordion>

  <Accordion title="Test across Python versions">
    Install and test with multiple Python versions:

    ```bash theme={null}
    uv python install 3.11 3.12 3.13
    ```

    Use CI/CD to automate testing across versions.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Python version not found">
    Install the specific version:

    ```bash theme={null}
    uv python install 3.12.7
    ```

    Or list available versions:

    ```bash theme={null}
    uv python list 3.12
    ```
  </Accordion>

  <Accordion title="Wrong Python version used">
    Check version resolution:

    ```bash theme={null}
    # In a project
    cat .python-version

    # Check what uv would use
    uv python find
    ```

    Override with `--python`:

    ```bash theme={null}
    uv run --python 3.12 main.py
    ```
  </Accordion>

  <Accordion title="Automatic downloads not working">
    Check if automatic downloads are disabled:

    ```bash theme={null}
    # Enable automatic downloads
    export UV_PYTHON_DOWNLOADS=automatic
    ```

    Or explicitly install:

    ```bash theme={null}
    uv python install 3.12
    ```
  </Accordion>

  <Accordion title="Environment issues after Python upgrade">
    Recreate the virtual environment:

    ```bash theme={null}
    rm -rf .venv
    uv sync
    ```

    Virtual environments are tied to specific Python installations.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Python versions concept" icon="book" href="../concepts/python-versions.md">
    Deep dive into Python version management
  </Card>

  <Card title="Command reference" icon="terminal" href="../reference/cli.md#uv-python">
    View all uv python commands
  </Card>

  <Card title="Running scripts" icon="play" href="./scripts.mdx">
    Execute Python scripts with uv
  </Card>

  <Card title="Working with projects" icon="folder" href="./projects.mdx">
    Create and manage projects
  </Card>
</CardGroup>