.python Version

However, simplicity is deceptive. This file acts as a between your development environment, your CI/CD pipeline, and your production runtime. It tells every tool in your stack: “Use exactly this Python version.”

asdf also understands .tool-versions (its native format), but it prioritizes .python-version if both exist. This allows teams mixing asdf and pyenv users to share the same file. 6. Platform Support (Heroku, Render, Vercel, GitHub Actions) The .python-version file is widely recognized across DevOps and PaaS providers. Heroku Heroku has used a runtime.txt file for years, but as of 2023, they also support .python-version . Create the file and commit it: .python version

monorepo/ ├── service_a/ │ ├── .python-version # 3.10.4 │ └── pyproject.toml ├── service_b/ │ ├── .python-version # 3.11.5 │ └── pyproject.toml For pyenv , you can set a version in ~/.pyenv/version (global). Not recommended for teams. Strategy 3: Environment Variables Override the version with PYENV_VERSION : However, simplicity is deceptive

Here are three scenarios that will convince you otherwise: Your colleague runs Python 3.10, but you have 3.12 installed. Suddenly, their use of datetime.UTC (new in 3.11) works fine on your machine but fails in CI. A .python-version file eliminates this ambiguity. Dependency Resolution Tools like pipenv and poetry read the current Python version to create deterministic lock files. If your environment changes, you may generate incompatible lock files. Tooling Integration Code formatters ( black ), linters ( ruff ), and type checkers ( mypy ) behave differently across major Python versions. Locking the version ensures reproducible linting results. 3. How pyenv Uses .python-version pyenv is the most popular Python version manager on macOS and Linux. It intercepts python commands and redirects them to the correct installed version. The Resolution Order When you run python inside a directory, pyenv looks for a .python-version file in the current directory, then parent directories, until it reaches your home folder. If none exists, it falls back to the global version (set via pyenv global ). Setting the Local Version To create a .python-version file, navigate to your project root and run: This allows teams mixing asdf and pyenv users

PYENV_VERSION=3.9.18 python scripts/legacy_script.py Keep .python-version alongside .nvmrc (for Node). Your shell can load both via direnv :

By adopting .python-version today, you stop guessing and start declaring. Your future self (and your teammates) will thank you.