Python Semantic Release

Test Status PyPI Version conda-forge Version Read the Docs Status

Automatic semantic versioning for python projects. This is a python implementation of semantic-release for JS by Stephan Bönnemann. If you find this topic interesting you should check out his talk from JSConf Budapest.

The general idea is to be able to detect what the next version of the project should be based on the commits. This tool will use that to automate the whole release, upload to PyPI and post changelogs to GitHub. You can run the tool on a CI service, or just run it locally.


python3 -m pip install python-semantic-release
semantic-release --help

Python Semantic Release is also available from conda-forge or as a GitHub Action. Read more about the setup and configuration in our getting started guide.

Getting Started

If you haven’t done so already, install Python Semantic Release following the instructions above.

There is no strict requirement to have it installed locally if you intend on using a CI service, however running with --noop can be useful to test your configuration.


Set version_variable in either setup.cfg or pyproject.toml. This option tells Python Semantic Release where to find and update the version number.

version_variable = semantic_release/

The example above uses the variable __version__ in semantic_release/ This variable must be initially created by hand - set it to the current version number:

__version__ = "0.0.0"

See also

  • branch - change the default branch.
  • commit_parser - use a different parser for commit messages. For example, there is an emoji parser.
  • upload_to_pypi - disable uploading the package to PyPI.
  • hvcs - change this if you are using GitLab.


semantic-release changelog

Print the changelog to stdout.

If the option --post is used and there is an authentication token configured for your vcs provider (GH_TOKEN for GitHub, GL_TOKEN for GitLab), the changelog will be posted there too.

semantic-release version

Figure out the new version number, update and commit it, and create a tag.

This will not push anything to any remote. All changes are local.

semantic-release publish

Publish will do a sequence of things:

  1. Update changelog file.
  2. Run semantic-release version.
  3. Push changes to git.
  4. Run build_command and upload the created files to PyPI.
  5. Run semantic-release changelog and post to your vcs provider.
  6. Attach the files created by build_command to GitHub releases.

Some of these steps may be disabled based on your configuration.

Running from

Add the following hook to your and you will be able to run python <command> as you would semantic-release <command>:

    from semantic_release import setup_hook
except ImportError:

Running on CI

Getting a fully automated setup with releases from CI can be helpful for some projects. See Automatic releases.