While being too specific, you can still version that file (meaning: not include it in the default
.gitignore), as :
- it will be used only by
(and, as noted by diavol in the comments,
setup-pythonGitHub Action uses this file to set the python version of the build environment)
- it is a good addition to the
README, in order to illustrate what version of python is recommended for the specific project,
- it can be overridden easily (if you are using
pyenv), or simply ignored (if you don’t have
As the article “How to manage multiple Python versions and virtual environments” states:
When setting up a new project that is to use Python 3.6.4 then
pyenv local 3.6.4would be ran in its root directory.
This would both set the version, and create a
.python-versionfile, so that other contributors’ machines would pick it up.
pyenvlooks in four places to decide which version of Python to use, in priority order:
PYENV_VERSIONenvironment variable (if specified).
You can use the
pyenv shellcommand to set this environment variable in your current shell session.
- The application-specific
.python-versionfile in the current directory (if present).
You can modify the current directory’s
.python-versionfile with the
- The first
.python-versionfile found (if any) by searching each parent directory, until reaching the root of your filesystem.
- The global version file. You can modify this file using the
If the global version file is not present,
pyenvassumes you want to use the “system” Python. (In other words, whatever version would run if
pyenvweren’t in your
None of these listed reasons indicate why
.python-versionshould not be stored in source control.
You can still have a section in the README saying that the version to be used is specified in the
- If someone is using
pyenvit works automatically for them.
- If not, then they’re in no worse of a position than they were if
.python-versionwas not under source control.
True: Keeping the
.python-version file under source control does ensure that
pyenv users have an automatic reference point for the Python version to be used, which could streamline the setup process for them. Moreover, it serves as a documented specification of the Python version for those who do not use
pyenv, assuming they are informed via the
README or other documentation that they should refer to this file for the Python version information.
However, one potential issue with storing the
.python-version file in source control could be the risk of unwanted modifications. Developers might accidentally commit changes to the
.python-version file as they switch between different Python versions in their local development environment, potentially leading to conflicts or confusion among the team.
To mitigate this risk, a possible strategy would be to include clear guidelines in the
README on how to handle the
.python-version file. That might include instructions to avoid committing changes to the file unless a deliberate decision has been made to update the Python version used by the project.
But if you have to rely on
README, I would instead put in that file instructions to activate a content filter driver, using a
instructions to activate the content filter driver:
git config filter.smudgeScript.smudge /path/to/your/smudgeScript git config filter.smudgeScript.clean "cat python-version.tpl"
And now, any checkout/clone would restore the right
.python-version while avoiding any unwanted modification in it.