# What is a .python-version file?

A `.python-version` file is a simple text file that specifies which Python version should be used for a particular project or directory. When present, Python version management tools like [uv](https://pydevtools.com/handbook/reference/uv.md) and [pyenv](https://pydevtools.com/handbook/reference/pyenv.md) automatically use the specified Python version when working in that directory.

The file contains a single line with a Python version specification, e.g.,

```
3.11.5
```

This approach provides environment-specific Python version control without requiring manual activation or configuration each time you work on a project.

## How .python-version Works

Version management tools scan the current directory and its parent directories for `.python-version` files. When found, they use the specified version for:

- Creating new virtual environments
- Running Python commands
- Installing packages
- Executing scripts

This automatic detection eliminates the need to remember or manually specify Python versions for different projects.

## Tool Support

Multiple Python tools recognize `.python-version` files:

- [uv](https://pydevtools.com/handbook/reference/uv.md): Uses the file to determine which Python version to install or use for project operations
- [pyenv](https://pydevtools.com/handbook/reference/pyenv.md): Originally popularized this convention for local Python version management
- pyenv-virtualenv: Integrates with pyenv to create version-specific environments
- [pipx](https://pydevtools.com/handbook/reference/pipx.md): Respects the file when creating isolated tool environments

The widespread adoption of this convention creates consistency across different Python toolchains.

## .python-version vs requires-python in pyproject.toml

While both `.python-version` and `requires-python` in [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) relate to Python versions, they serve fundamentally different purposes:

### .python-version: Development Environment Control

The `.python-version` file controls the specific Python version used during development. For example, if the file contains `3.11.5`, Python will be:

- Pinned to an exact version (3.11.5, not 3.11.x)
- Local to your development environment
- Used by version managers to select interpreters
- Not distributed with your package
- Development-time configuration

### requires-python: Package Compatibility Declaration

The `requires-python` field in `pyproject.toml` declares compatibility requirements for your [package](https://pydevtools.com/handbook/explanation/what-is-a-python-package.md):

```toml
[project]
requires-python = ">=3.9"
```

- Specifies minimum (and optionally maximum) supported versions
- Distributed with your package
- Used by package installers to verify compatibility
- Runtime constraint that affects end users
- Package metadata that influences installation decisions

### Relationship Between the Two

These specifications work together but address different concerns:

- `.python-version` ensures consistent development environments across team members
- `requires-python` ensures your package works for users with compatible Python versions

For example, you might develop with Python 3.11.5 (`.python-version`) while supporting Python 3.9+ (`requires-python = ">=3.9"`). This allows you to use a modern development environment while maintaining broad compatibility.

> [!WARNING]
> The version in `.python-version` must satisfy the `requires-python` constraint. If `.python-version` specifies Python 3.8 but `requires-python = ">=3.9"`, tools like uv will report an incompatibility error.

## Best Practices

Consider these guidelines when using `.python-version` files:

- Pin specific versions for reproducible development environments
- Commit to version control to ensure team consistency
- Align with project requirements - ensure the pinned version satisfies `requires-python`
- Update thoughtfully when upgrading Python versions across the project

The `.python-version` file represents a simple but powerful convention for managing Python versions in development workflows, providing automatic environment selection without complex configuration or manual intervention.

## Learn More

* [How to change the python version of a uv project](https://pydevtools.com/handbook/how-to/how-to-change-the-python-version-of-a-uv-project.md)
* [How to switch from pyenv to uv for managing Python versions](https://pydevtools.com/handbook/how-to/how-to-switch-from-pyenv-to-uv-for-managing-python-versions.md)
* [How to fix Python version incompatibility errors in uv](https://pydevtools.com/handbook/how-to/how-to-fix-python-version-incompatibility-errors-in-uv.md)