: Avoid putting a .python-version file in your home directory, as this can override your intended global settings in unexpected ways.
💡 : While this file sets the Python executable , you should still use a tool like venv or poetry to manage your project's specific libraries . If you'd like to set this up, let me know:
But asdf can be configured to read .python-version via a shim or by symlinking .tool-versions . Many teams prefer .tool-versions for consistency across languages.
Monorepos (multiple projects in one repository) pose a challenge: different subprojects may need different Python versions.
add it to .gitignore . This file ensures that every clone, branch, and CI run uses the same Python version. .python version
pyenv install X.Y.Z
If you use pyenv , you can set a local version for your current directory with a single command: pyenv local 3.11.5 Use code with caution.
It is important to understand where this file fits alongside other Python configuration formats. File Format Primary Purpose Defines the global/local runtime interpreter version. pyenv , mise , asdf runtime.txt Dictates the Python runtime version for cloud deployment. Heroku, Azure pyproject.toml
Check if the setup was successful. The shell should reflect your specified local build, even if your global machine default is different. python --version # Output: Python 3.12.2 Use code with caution. Best Practices: Source Control and CI/CD : Avoid putting a
asdf writes the same .python-version file but interprets it through its own shim system. The key advantage: you can manage Python, Node, and Rust versions from a single tool.
Switches versions instantly using simple declarative commands like pyenv local 3.12 . 2. Pyenv-win (Windows)
You can create this file manually or via your version manager's command line:
Rye is a modern, unified one-stop shop for Python development created by Armin Ronacher. Rye treats the .python-version file as a first-class citizen to pin toolchains for reproducibility. 4. ASDF / Mise Many teams prefer
PYENV_VERSION=3.9.18 python scripts/legacy_script.py
By combining .python-version with a .envrc file, you can fully automate environment setup:
mise (formerly rtx ) is a polyglot tool runtime manager written in Rust. It serves as a faster alternative to asdf and pyenv . It natively reads .python-version files to activate Python environments instantly upon directory entry.