: A major milestone for speed, delivering performance increases of
In modern development, different projects often require different Python versions. For example, an older legacy app might need , while a new data science project requires Python 3.12 . Managing these manually by changing global paths is error-prone. Tools like pyenv solve this by looking for a .python-version file. How the .python-version File Works
A .python-version file only defines the core underlying language runtime engine. It does install or isolate project dependencies. You must still combine this file with dependency tools like venv , virtualenv , or poetry to avoid cluttering your base interpreter paths. Troubleshooting: Git Changes Aren't Reflecting Locally
Pyenv is the most popular tool for managing multiple Python versions. To create the file automatically, run: pyenv local 3.11.5 This command creates a .python-version file in your current directory. From now on, whenever you enter this folder, pyenv will set Python to 3.11.5. Using asdf
: Always commit this file to your repository so other developers' environments sync automatically. Avoid Defaults : Don't just put ; use a specific version like to prevent "it works on my machine" bugs. : Keep it in the
: Code runs directly without a separate compilation step and is compatible across Windows, macOS, and Linux [5.4].
# Sets the local version to 3.10.5 pyenv local 3.10.5
A .python-version file contains a single string—the version number of Python required for a project (e.g., 3.12.1 ). When you navigate into a folder containing this file, your version manager detects it and instantly switches your active Python interpreter to match that specific version. Why Use It?
And it worked.
Multiple tools across the Python ecosystem recognize and respect the .python-version file.
This command automatically generates a .python-version file containing the string 3.11.5 . Whenever you cd into this folder, pyenv will prioritize this version over your global default. 2. Manual Creation
Major tools and platforms recognize this file to ensure environment consistency:
Remember:
Alternative: let pyenv write the file: