Python Semantic Release#

Ruff test-status pypi conda-forge docs pre-commit

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 an artifact repository 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.

Documentation Contents#

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.

Generating your configuration#

Python Semantic Release ships with a command-line interface, semantic-release. You can inspect the default configuration in your terminal by running

semantic-release generate-config

You can also use the -f/–format option to specify what format you would like this configuration to be. The default is TOML, but JSON can also be used.

You can append the configuration to your existing pyproject.toml file using a standard redirect, for example:

semantic-release generate-config --pyproject >> pyproject.toml

and then editing to your project’s requirements.

Setting up version numbering#

Create a variable set to the current version number. This could be anywhere in your project, for example

from setuptools import setup

__version__ = "0.0.0"

   # And so on...

Python Semantic Release can be configured using a TOML or JSON file; the default configuration file is pyproject.toml, if you wish to use another file you will need to use the -c/--config option to specify the file.

Set version_variables to a list, the only element of which should be the location of your version variable inside any Python file, specified in standard module:attribute syntax:


version_variables = [""]

See also

Setting up commit parsing#

We rely on commit messages to detect when a version bump is needed. By default, Python Semantic Release uses the Angular style. You can find out more about this in Commit Parsing.

See also

  • branches - Adding configuration for releases from multiple branches.

  • commit_parser - use a different parser for commit messages. For example, Python Semantic Release also ships with emoji and scipy-style parsers.

  • remote.type - specify the type of your remote VCS.

Setting up the changelog#

See also

Creating VCS Releases#

You can set up Python Semantic Release to create Releases in your remote version control system, so you can publish assets and release notes for your project.

In order to do so, you will need to place an authentication token in the appropriate environment variable so that Python Semantic Release can authenticate with the remote VCS to push tags, create releases, or upload files. You should use the appropriate steps below to set this up.

GitHub (GH_TOKEN)#

Use a personal access token from GitHub. See Configuring push to Github for usage. This token should be stored in the GH_TOKEN environment variable

To generate a token go to and click on Personal access token.


A personal access token from GitLab. This is used for authenticating when pushing tags, publishing releases etc. This token should be stored in the GITLAB_TOKEN environment variable.


A personal access token from Gitea. This token should be stored in the GITEA_TOKEN environment variable.


Bitbucket does not support uploading releases but can still benefit from automated tags and changelogs. The user has three options to push changes to the repository:

  1. Use SSH keys.

  2. Use an App Secret, store the secret in the BITBUCKET_TOKEN environment variable and the username in BITBUCKET_USER.

  3. Use an Access Token for the repository and store it in the BITBUCKET_TOKEN environment variable.

See also

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:


Only the version, publish, and changelog commands may be invoked from in this way.

Running on CI#

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