Don’t replace your system Python. Seriously, don’t. Use dedicated version managers:
Once you have the right Python version, pair it with virtual environments (venv or uv venv). Never install packages globally.
If the requested version isn't installed, pyenv will warn you:
pyenv: version `3.11.5' is not installed (set by /path/to/.python-version)
Simply run:
pyenv install 3.11.5
While Lambda doesn't read .python-version directly, you can use it to generate your deployment image:
docker build --build-arg PYTHON_VERSION=$(cat .python-version) .
Here's a brief history of major Python versions:
Python 3.14 (expected 2025-ish) is rumored to bring more speed improvements and maybe – maybe – a JIT compiler. .python version
And the big question: Will there ever be a Python 4?
Probably not. The core team learned their lesson. They now prefer "forever 3.x, with gradual changes."
Python is no longer a language that breaks everything every decade. It’s a stable, evolving ecosystem – like a city that builds new subway lines without tearing down the old ones.
In your CI pipeline, you can read the file dynamically: Don’t replace your system Python
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version-file: '.python-version'
This ensures your CI runs the exact same version as developers.
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-3.11.5
Note: Heroku requires the python- prefix on the version string. Once you have the right Python version, pair
The .python-version file should be placed in the root directory of your Python project—the same folder containing pyproject.toml, setup.py, or requirements.txt.
Example structure:
my_project/
├── .python-version <-- Here
├── .gitignore
├── pyproject.toml
├── src/
│ └── my_package/
└── tests/