So you completed your wonderful new project, all your test are successful (you test code, don't you?) and you just want to ship the new version and call it a day. Well, you just have to go and change the version number in your install script and save. Oh, right, you also have to open a feature branch, so that you may record the version update in your Git history. Well, easily done. Damn! You forgot to change the version number in the file...

Managing the version number of a project is not easy. Not only you need to think about the versioning scheme and what part of the version to increase (see this post for some tips on this matter), but you also need to remember in which files you put the actual version number, and, depending on your workflow, to correctly manage the version control system commits.

Punch is a small tool that aims to simplify the latter parts, that is the management of the version number update process. Punch is a young project but the underlying structure should be flexible enough to allow the implementation of advanced usage cases that may arise in the future.

Punch logo


  • Written in Python, but manages every kind of text file
  • May implement different versioning schemas
  • Currently supports integer version parts and multiple value integer parts
  • Version parts may be explicitly set to given values
  • The same version number can be represented in different ways using Jinja2 templates
  • Each managed file may override the global behaviour with custom settings
  • Can automatically commit using Git or git-flow
  • May optionally create annotated commits
  • Can simulate the version upgrade and show what is going to happen


You may install Punch in your virtual environment (or in your system) directly from PyPI

pip install

and you will have the punch executable available.

Useful links

Feel free to submit your issues or pull requests, contributions are welcome.