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 and pyenv 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: Uses the file to determine which Python version to install or use for project operations
• pyenv: Originally popularized this convention for local Python version management
• pyenv-virtualenv: Integrates with pyenv to create version-specific environments
• pipx: 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 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:

[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.

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
• How to switch from pyenv to uv for managing Python versions
• How to fix Python version incompatibility errors in uv