Should I check .python-version in to source control?

[nchammas]

What are the general arguments for and against checking .python-version in to source control for a given project?

I'm working on a private project with a small team. I'm wondering if it hurts or helps more to pin everyone to the same version of Python, given that the project is only used by us and doesn't currently need to support multiple versions of Python.

What are people's experiences with this idea?

[wlritchi]

Disclaimer: Most of my software development experience thus far has not been with Python, so my comments are based on general experience with managing versions of any dependency, rather than Python-specific guidance.

In my experience, it's generally helpful to keep your environments as similar as possible. As much as we'd like to imagine that every dependency (including Python) will not introduce breaking changes, the reality is that differences in behaviour can and will introduce bugs in some environments, that you will be unable to reproduce in other environments. The biggest risk here is if the production environment is different from the development or testing environments, because then you may encounter bugs that didn't appear during development or testing.

If you are able to ensure that the production environment will always use a particular version of Python, I would recommend also pinning development and test environments to that version. This reduces the number of variables that you will have to deal with when troubleshooting issues. In your case, it seems like the project may only be run directly out of the repo (so, if there is a .python-version, all uses will respect that version). Pinning the version here seems reasonable.

On the other hand, if the deployed version of your project will run against a variety of Python versions, you're going to want an opportunity to catch issues with these versions before they occur in production. In that case, the most robust solution is a good test suite that can be run using each supported version. For small projects in particular, this may be more work than you'd like to put in. If you aren't going to use a robust test suite, but still want to support multiple versions of Python, perhaps allowing different developers to end up using different Python versions will give at least some opportunity to catch issues early.

You might notice that there's been a recent trend towards software containerization, using Docker and similar technologies. In my mind, the biggest argument in favour of containerization is precisely that it allows developers to pin the versions of all of the software they depend on. The popularity of this trend suggests that people are finding it beneficial to be able to pin their dependency versions this way. Something as heavy as Docker may well be overkill for a small project, but pyenv is a pretty easy way to at least pin the Python-related dependency versions.

[joshfriend]

I have always committed it for years now. Keeping your local dev/test environment as similar as possible to your CI environment and deployed environments is a good idea. AWS Elastic Beanstalk has python 3.8.5, an embedded linux project I work on is at something like 3.8.2. It has helped me avoid accidentally using new APIs and features that are not yet available in my deploy environment.