Python version management doesn't have to be a source of friction. By understanding the difference between and virtual environments , leveraging the right tool for your use case, and following a few simple best practices, you can work across dozens of projects with confidence.
: Your version manager detects the directory change via a shell hook.
import random import string
The is a plain-text configuration file used in modern software development to explicitly lock and automate Python environment settings for a given project directory. Originally popularized by the Python version manager pyenv , it is now standard across industry-leading tools like Astral's uv , GitHub Actions, and cloud deployment platforms like Heroku and Render. By automatically matching local development configurations with production requirements, this file eliminates the classic developer headache of "it works on my machine". What is a .python-version File? .python version
The quickest way to check your installed version is through your system's terminal. python --version Specific to Python 3: python3 --version Windows Launcher: py --version
Modern, ultra-fast Python packaging tools developed by Astral (like Rye and UV) natively respect the .python-version file. They use it to pin the workspace toolchain and will even offer to download the missing Python version automatically if it is not found on your system. 3. Asdf-vm / Mise
pyenv local 3.10 python -m venv .venv source .venv/bin/activate Python version management doesn't have to be a
When you type python , your shell finds a pyenv shim instead of the system Python. That shim determines which version to use by checking (in order):
When you enter a directory containing this file, your version manager reads the version string inside and sets that version as the active Python for your current shell session. This ensures that every developer working on the project uses the same environment. How to Create the File
pyenv version
For most developers, sticking to the latest (e.g., 3.12 and 3.13) is a safe balance between new features and library support.
The file is not a native feature of Python itself but is recognized by popular third-party managers: