Should we gitignore the .python-version file?

Question

I have a .python-version file, and when I create a Python repo with github and specify that it should have a .gitignore, it adds the .python-version file to it. It seems to me that that file should NOT be ignored since other people running the code on different machines would want to know what version of Python they need.

So why is it .gitignored?

Pucker

Git itself won't automatically add a .gitignore file. So I suspect that what you're asking is why GitHub has this behavior. My guess is that they're just excluding all files that start with . by default -- there is no good reason I know of to ignore .python-version. – Orangutan

@DanielPryden: the answer below states an excellent reason; if you have Python 3.7.2 installed but the .python-version file states the project owner used 3.7.1, then we both can continue to work with this project just fine outside of specific point release bugfixes. – Coligny

I much prefer Pipenv, which lets you specify Python versions with as much resolution as needed. – Coligny

Pyenv also allows specifying the Python version with the resolution you need. – Knighthood

Answer 1

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 pyenv
  (and, as noted by diavol in the comments, setup-python GitHub 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 pyenv).

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.4 would be ran in its root directory.
This would both set the version, and create a .python-version file, so that other contributors’ machines would pick it up.

But:

pyenv looks in four places to decide which version of Python to use, in priority order:

1. The PYENV_VERSION environment variable (if specified).
   You can use the pyenv shell command to set this environment variable in your current shell session.
2. The application-specific .python-version file in the current directory (if present).
   You can modify the current directory's .python-version file with the pyenv local command.
3. The first .python-version file found (if any) by searching each parent directory, until reaching the root of your filesystem.
4. The global version file. You can modify this file using the pyenv global command.
   If the global version file is not present, pyenv assumes you want to use the "system" Python. (In other words, whatever version would run if pyenv weren't in your PATH.)

---

None of these listed reasons indicate why .python-version should 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 .python-version file.

• If someone is using pyenv it works automatically for them.
• If not, then they're in no worse of a position than they were if .python-version was 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 .gitattributes declaration.

^{(image from "Customizing Git - Git Attributes", from "Pro Git book")}

• .gitignore

  .python-version
  

• .gitattributes

  .python-version filter=smudgeScript
  

• 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.

Dudley

None of these listed reasons indicate why .python-version should 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 .python-version file. If someone is using pyenv it works automatically for them. If not then they're in no worse of a position than they were if .python-version was not under source control. – Knighthood

@BrendanMaguire Good point. I have edited the answer to address your comment. – Dudley

"it will be used only by pyenv" - also setup-python github action uses this file to set the python version of the build environment. – Bremerhaven

@Bremerhaven Good point, thank you for the feedback. I have included your comment in the answer for more visibility. – Dudley

Answer 2

The reason why .python-version should be gitignored is because its version is too specific. Tiny versions of Python (e.g. 2.7.1 vs 2.7.2) are generally compatible with each other, so you don't want to lock down to a specific tiny version. Furthermore, many Python apps or libraries should work with a range of Python versions, not just a specific one. Using .python-version indicates that you want other developers to use an exact, specific Python version, which is usually not a good idea.

If you want to indicate the minimum Python version needed, or otherwise a version range, then I believe documenting that in a README is a more appropriate solution.

Titfer

Pyenv supports specifying the version down to the major, minor or patch level. i.e. if the .python-version file contains 2.7 then it will use the latest 2.7.* that is installed in that environment. In your case above it would use 2.7.2. – Knighthood

Answer 3

It can also be a bit problematic when using python virtual environments, as people may want to use virtual environment names different than 3.7.2/envs/myvenv.

Placida

Answer 4

Old post but still relevant.

My answer would be "it depends".

The name of a virtual env can also be used in .python-version, if it is managed with the help of the virtualenv plugin of pyenv. This makes this file pretty useless it the project is managed on a public Git repo and you can exclude it (but not to do is harmless as told in other answers).

But (and I am in this situation) if you manage the project on a private repo and share virtual envs, it can make sense to not exclude it from Git. This allows you to work with a different environment (including the Python version) on an experimental branch of the project. Of course, it would have been far cleaner to fork or clone the original project and experiment with the new env in the copy, but sometimes it easier to just create a new branch.

At the end of the day, IMHO there is no universal answer to the question, and it depends on your workflow.

Unpack

Answer 5

Well sir I think answer to your question is YES. I just openend GitHub official repo and checked the project gitignore.

It showed .python-version file mentioned there.

And if it's not getting ignored you can simply check for correct way to mention.

Prioress

-1, this doesn't answer the "why" part of the question and doesn't really add any information that OP didn't already know and specify in the question. – Leaseholder

actually it is mentioned but commented out with an explanation For a library or package, you might want to ignore these files since the code is # intended to run in multiple environments; otherwise, check them in github.com/github/gitignore/blob/main/Python.gitignore#L85-L88 – Ecuador