Skip to main content

⚠️ Warning ⚠️
Simple Releaser is beta software and still being tested. Expect rough edges and breaking changes.

Simple Releaser

Simple Releaser is a configurable command-line tool for validating, building, tagging, and publishing Python package releases.

The PyPI distribution is named simple-releaser. Once installed, it can be invoked as either simple-releaser or release.

Simple Releaser grew out of a direct copy of the release workflow used by the QRtsy Project, which was itself just a copy of similar tooling that I've used in several other projects. This version of the tool has since been updated significantly to generalize it in order to accommodate different release workflows. While Simple Releaser is very configurable, it is deliberately designed to be simple and is unlikely to grow much beyond this initial vision. If you've got more complex needs, you may wish to consider some alternatives.

Project assumptions

Run Simple Releaser from a directory containing the releaser configuration (releaser.toml by default). This directory may also be the project root, or the releaser configuration may point at a separate project directory.

The project being released is expected to have:

  • Project configuration, including name and version, in pyproject.toml.
  • A changelog file named CHANGELOG.md, with Unreleased and version sections.
  • A Git repo with an origin remote (or configure repo_remote to select a different remote).

When publishing a repository release, the project is also expected to have:

  • A repository hosted by Codeberg, Forgejo, Gitea, GitHub, or GitLab, including supported self-hosted instances.
  • Publication credentials configured through the publisher, environment, or system keyring, as appropriate for the destination.

Installation

A convenient way to install Simple Releaser as a standalone command-line tool is with pipx:

pipx install simple-releaser

Once installed, Simple Releaser can then be invoked as either:

release

or:

simple-releaser

Commands

The available CLI commands are:

$ release --help

Simple Releaser

Validate, build, and publish Python project releases.

Usage:
  release [options] COMMAND [arguments]

Main command:
  run              Run the complete release workflow

Release steps:
  validate         Validate release readiness
  check            Run configured project quality checks
  build            Build and archive the current version
  tag              Create and push the release tag
  to_repo          Publish the repository release
  to_index         Publish distributions to a package index

Setup and inspection:
  init             Initialize Simple Releaser configuration
  show             Show resolved configuration and project information
  is_clean         Check for a clean Git repository
  auth             Manage publication authentication
  help             Show help for Simple Releaser or a command

Options:
  -h, --help       show this help message and exit
  -V, --version    show the version number and exit
  --dry-run        show what would be done without making changes

Initialization

Simple Releaser requires a configuration file in the current working directory. By default it is named releaser.toml. To use a different filename, set the RELEASER_CONFIG environment variable to the desired name.

Run release init from the directory where the releaser configuration should live:

release init

If that directory contains the pyproject.toml for a project, Simple Releaser creates a minimal releaser.toml for that project. Otherwise it prompts for the project directory and then records the given project_path in the generated configuration. Relative paths are used when possible. An existing releaser configuration is never overwritten.

The init command also creates a text file with configuration examples that is named with the same prefix as the releaser configuration file so both files will always be generated near each other. Default is releaser-examples.txt.

Configuration

While the existence of a configuration file is required, its contents are optional unless overrides to default configuration are desired. An exception is when the current working directory does not also contain the project's pyproject.toml. If the project lives elsewhere, project_path is required and must identify a directory containing pyproject.toml. Relative paths are resolved from the directory containing the releaser configuration; absolute paths are also accepted. In this case, the minimum configuration might be:

project_path = "../my-project"

Set auto_confirm = true at the top level to allow package-index publication without an interactive confirmation prompt, for example in a deliberately unattended release workflow. It defaults to false.

By default, subprocess_output = "live" lets external commands display output as they run, including progress bars and error messages. Set subprocess_output = "errors" to hide successful subprocess output and show captured diagnostics only when a command fails. In errors mode, Simple Releaser redacts managed authentication tokens from those diagnostics. In live mode, external tools write directly to the terminal and are responsible for protecting any credentials they use. Simple Releaser's own status messages are displayed in either mode.

Build artifacts are archived under _releases/<version>/ beside the releaser configuration file. If _releases is in the project directory, Simple Releaser creates a .gitignore file to exclude it from Git. Set gitignore_releases = false at the top level to disable this behavior.

Configuration default values

For reference, the default values for the configuration settings are as follows:

project_path = "."
tag_prefix = "v"
auto_confirm = false
subprocess_output = "live"
gitignore_releases = true
index_upload_url = "https://upload.pypi.org/legacy/"  # PyPI default

[commands]
check = ""
build = "{python} -m build --outdir {output}"
publish = "{python} -m twine upload {dist_dir}/*"
run = "validate check build tag to_repo to_index"

[auth]
keyring = "keyring"

[auth.repo]
source = "environment"

[auth.index]
source = "publisher"

See later sections of this readme for more details about each of these settings. See the examples file generated by init for authentication settings and examples.

Configurable commands

The [commands] section currently supports check, build, publish, and run. A value may be either a shell-like string or a TOML array of argument strings. The following forms are equivalent:

check = "uv run pytest"
check = ["uv", "run", "pytest"]

Quoting in a string may be used to preserve spaces within one argument:

check = 'python -c "print(1 + 1)"'

Command strings use POSIX quoting on macOS/Linux and Windows argument quoting on Windows. Simple Releaser executes commands directly without a shell, so shell features such as pipes or command chaining require an explicitly invoked shell. For complex arguments, TOML arrays avoid platform-specific quoting. For example, on Windows:

[commands]
check = ['C:\Program Files\Python\python.exe', "-m", "pytest"]

An empty string or empty array disables the task associated with that configured command. For example:

[commands]
check = ""    # disables 'check' task
build = ""    # disables 'build' task
publish = ""  # disables 'to_index' task
run = ""      # disables the entire pipeline

Configuring check

The configured check command is the project's generic handoff to its own release-readiness policy. Tests, linters, type checks, documentation checks, project-specific validation, or any other prerequisite can live behind this one command. Since that policy is project-specific, check is disabled by default and must be customized for the project:

[commands]
check = ""

A useful pattern is to point check at a project task runner, so the same check task can be used during development, in CI, and during a release without duplicating workflow configuration.

The Simple Releaser project dogfoods its own tooling for releases of itself and uses Poe the Poet as the task runner for its check task. This is defined in the project's releaser.toml like so:

[commands]
check = "hatch run poe check"

See the project's pyproject.toml for the poe check task configuration to see what it runs as part of its pre-release project check.

Poe the Poet is optional. See Project Checks and Task Runners for a discussion of various other task runners that can be used for this.

Configuring build and publish

By default, Simple Releaser builds its release artifacts with build and publishes with twine:

[commands]
build = "{python} -m build --outdir {output}"
publish = "{python} -m twine upload {dist_dir}/*"

Custom build and publish commands may also use {python}, which expands to the absolute path of the Python interpreter running Simple Releaser. This lets an override deliberately use a tool installed alongside Simple Releaser rather than whichever python happens to be on PATH.

The {output} placeholder in build is replaced with the temporary staging dist/ directory where the build command must write its distributions. A non-empty custom build command must include {output}. Publish commands may use {release_dir} for the release archive root and {dist_dir} for its distribution subdirectory.

Custom publish commands may use {index_url} to insert the configured upload URL or specify the destination directly in the command. Otherwise, Simple Releaser attempts to automatically identify the appropriate environment variable for the publisher and uses it to direct uploads to the configured package index. See releaser-examples.txt for examples.

Use releaser show to inspect the package index destination and urls selected by Simple Releaser. The default package index is PyPI but this can be overridden via the index_upload_url config setting.

For TestPyPI, use its upload URL (and use a separate TestPyPI token):

index_upload_url = "https://test.pypi.org/legacy/"

For a custom index, provide its HTTPS upload endpoint. Project-page and PyPI-compatible JSON-API endpoints are optional. The optional JSON-API endpoint is used to check whether the release was already published to the index.

index_upload_url = "https://packages.example.com/legacy/"
# index_project_base_url = "https://packages.example.com/project"
# index_api_base_url = "https://packages.example.com/pypi"  # only for compatible JSON APIs

The default build and publish commands work with most standards-compliant build backends declared in the [build-system] section of a project's pyproject.toml configuration. Users that prefer their project-management tool's native build and publish commands can override the defaults. Typical equivalents are:

# Poetry
build = "poetry build --output {output}"
publish = "poetry publish --repository releaser --dist-dir {dist_dir}"

# Hatch
build = "hatch build {output}"
publish = "hatch publish --no-prompt {dist_dir}"

# uv
build = "uv build --no-sources --out-dir {output}"
publish = "uv publish {dist_dir}/*"

# PDM
build = "pdm build --dest {output}"
publish = "pdm publish --no-build --dest {dist_dir}"

For these publishers, Simple Releaser automatically supplies the configured upload URL using the following environment variables:

Publisher Auto-detected environment variable Notes
Twine TWINE_REPOSITORY_URL URL takes precedence over .pypirc
Poetry POETRY_REPOSITORIES_RELEASER_URL Command selects --repository releaser
Hatch HATCH_INDEX_REPO Upload URL for the publisher
uv UV_PUBLISH_URL Upload URL for the publisher
PDM PDM_PUBLISH_REPO Upload URL for the publisher

For an unrecognized publisher, configure publish_index_env to the environment variable expected by the publisher, or use {index_url} directly in the command, or include the destination explicitly in the custom command like so:

[commands]
publish = "uv publish --publish-url https://packages.example.com/legacy/ {dist_dir}/*"

This last "explicit-url-in-command" option disables Simple Releaser's index-aware verification features so it's recommended to only use this option as a last resort.

The default PyPI publisher uses Twine's normal authentication mechanisms, including keyring, .pypirc, and TWINE_* environment variables. PyPI and TestPyPI have separate accounts and tokens; repository-specific .pypirc or keyring entries are the clearest way to keep those credentials distinct. For repository-host settings, Simple Releaser checks the process environment first and then falls back to the .env file beside the releaser configuration.

Run release auth check to check whether configured tokens can be retrieved and meet basic format requirements. This does not verify token validity against the destination service or check publication permissions. Publisher-managed tokens cannot be retrieved directly by Simple Releaser, so they cannot be checked.

To store a token with Simple Releaser, install the keyring CLI separately, then run release auth set {repo,index}. This command stores the token and then prints a configuration snippet to add to releaser.toml. release auth delete {repo,index} deletes the token from the keyring.

Configuring run

The commands.run setting specifies the sequence of tasks executed by the run command. Its default value is:

[commands]
run = "validate check build tag to_repo to_index"

The available tasks are validate, check, is_clean, build, tag, to_repo, and to_index.

validate checks release readiness, including the project version and release notes. It is the first task in the default sequence, but custom sequences may omit it. Omitting validate skips these release readiness checks and may allow an invalid release to proceed.

is_clean is an optional task that checks that the Git working tree is clean. This check is already performed when building a new release, so including is_clean in the run sequence is usually unnecessary.

Release archives and interrupted releases

A successful build creates _releases/<version>/, containing a dist/ subdirectory for distributions, RELEASE.md with the release notes, SHA256SUMS for distribution checksums, and BUILD_COMMIT identifying the Git commit used to build the archive. A release can contain multiple wheels and at most one source distribution (.tar.gz).

If a run sequence is interrupted after the archive is built, running it again reuses the verified archive instead of rebuilding. In that case, check and build are skipped, even if they appear in commands.run. The remaining tasks still execute, including validate if configured. The archived commit is used for tagging, so later changes to HEAD or the working tree do not change which source revision is released. An existing archive must pass verification before it can be reused.

To force a new build, invoke release build directly. Replacing an existing archive requires interactive confirmation and is refused if the release tag already exists. You can choose whether to retain the previous archive in _releases/.backups/ after a successful replacement. An interrupted installation may also leave a backup in the same location for manual recovery.

Local and CI release strategies

The run sequence also determines where the release process stops.

The default run sequence performs the complete release locally:

[commands]
run = "validate check build tag to_repo to_index"

An alternative common release pattern, especially when more than one developer is empowered to create releases, is to delegate release tasks to a remote CI/CD platform. Simple Releaser easily supports the remote CI/CD release pattern.

For a project with a remote CI/CD that publishes after a release tag is pushed, omit the local publication tasks from the run sequence:

[commands]
run = "validate check build tag"

Here the local build acts as a packaging preflight. Simple Releaser verifies that the distributions can be built and archived before tag creates and pushes the release tag. The remote workflow may then rebuild the tagged source and publish its own artifacts.

Projects with expensive, platform-specific, or otherwise CI-authoritative builds may omit the local build as well:

[commands]
run = "validate check tag"

In this release sequence, Simple Releaser first performs its built-in release validation before running the project's configured check command and then creates and pushes the release tag. The remote workflow is responsible for both building and publishing. This avoids a duplicate local build but a packaging failure will not be discovered until after the release tag has been pushed.

For a concrete GitHub Actions CI/CD workflow using PyPI Trusted Publishing, see GitHub Actions and PyPI Trusted Publishing.

Repository host

Simple Releaser normally determines the repository host and repository identifier from the project's Git origin by default. HTTPS and SSH remotes on codeberg.org, gitea.com, github.com, and gitlab.com are recognized.

When automatic detection is insufficient, the following settings can override it:

  • repo_remote selects the Git remote for release tag lookups and pushes (default: origin). For example, repo_remote = "upstream".
  • repo_host selects the hosting service: codeberg, forgejo, gitea, github, or gitlab.
  • repo_base_url overrides the server URL derived from the selected Git remote. This is primarily useful for self-hosted instances. Specify the web URL, not the API URL. Simple Releaser constructs API URLs automatically.
  • <HOST>_REPOSITORY environment variable specifies the repository receiving the release, overriding the repository identifier derived from Git. For example, GITLAB_REPOSITORY=group/project.

For example, to use a self-hosted GitLab instance:

repo_host = "gitlab"
repo_base_url = "https://git.example.org"

Repository overrides may be set as environment variables or in the .env file beside releaser.toml; an exported environment variable takes precedence over the same .env entry.

To publish to a Codeberg repository, set CODEBERG_TOKEN. Set CODEBERG_REPOSITORY=owner/repo to override the repository identifier derived from the Git origin.

To publish to a Forgejo repository, set FORGEJO_TOKEN and configure repo_host = "forgejo". Simple Releaser derives the instance URL from the Git selected Git remote unless repo_base_url overrides it. Set FORGEJO_REPOSITORY=owner/repo to override the derived repository identifier.

To publish to a Gitea repository, set GITEA_TOKEN. Set GITEA_REPOSITORY=owner/repo to override the derived repository identifier. For self-hosted Gitea, configure repo_host = "gitea"; use repo_base_url only when the instance URL cannot be inferred correctly from the Git origin.

To publish to a GitHub repository, set GITHUB_TOKEN. Set GITHUB_REPOSITORY=owner/repo to override the derived repository identifier. The GitHub token must have permission to create releases and upload release assets.

To publish to a GitLab.com repository, set GITLAB_TOKEN. Set GITLAB_REPOSITORY=namespace/repo to override the derived repository identifier. Nested namespaces such as group/subgroup/repo are supported. The GitLab token must have permission to create releases, upload project files, and create release asset links.

Package index

The to_index task publishes to production PyPI by default. To publish to TestPyPI, which requires a separate account and token, configure:

index_upload_url = "https://test.pypi.org/legacy/"

Custom package indexes are supported through an HTTPS index_upload_url. See the preceding publishing section for full examples. The URL is supplied to supported publishers via an automatically selected environment variable, a publish_index_env override, or the {index_url} command placeholder, so a custom command does not need to embed a fixed destination.

Before uploading, Simple Releaser checks for an existing release when the index supports PyPI's JSON API. It compares published filenames and SHA-256 checksums with the archived distributions to identify matches, missing files, or conflicts.

Pre-upload checks are supported automatically for PyPI and TestPyPI. For a custom package index, enable by setting index_api_base_url, but only if it implements the PyPI-style endpoint. Note that the PyPI-style JSON API is different from the standardized Simple Repository API (PEP 503/691), which package installers typically use.

Support for the Simple Repository API is planned but, for now, if your index doesn't support PyPI's JSON API, just leave index_api_base_url unset. Simple Releaser will then skip the pre-upload check. This pre-upload check is optional and isn't required for a successful release.

Development

For development purposes, some project checks and a test runner are defined as Poe tasks:

poe lint
poe format-check
poe typecheck
poe test

# Run all of the above
poe check 

The test suite can also be run across the matrix of supported Python versions, which currently includes Python 3.11, 3.12, 3.13, and 3.14, using another Poe task:

poe test-matrix

A separate packaging smoke test creates isolated test environments, installs the Simple Releaser wheel and sdist package artifacts, and performs some basic checks to verify that the packages are actually installable. This test can be invoked with another Poe task:

poe package-smoke

Finally, a more thorough check meant for CI runs the linters, type checks, tests across all supported Python versions, and the packaging smoke test. It can also be invoked locally via a Poe task:

poe ci

Metadata

Release files for simple-releaser 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simple-releaser 0.4.0
File Size Uploaded Provenance Actions
simple_releaser-0.4.0.tar.gz 119.1 kB Without provenance Details for simple_releaser-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simple-releaser 0.4.0
File Interpreter ABI Platform Actions
simple_releaser-0.4.0-py3-none-any.whl Python 3 none any Details for simple_releaser-0.4.0-py3-none-any.whl

Total release size: 181.1 kB

Release files / simple_releaser-0.4.0.tar.gz

Download URL simple_releaser-0.4.0.tar.gz
Size 119.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a225e30ea843bcb1d3e23c77b8afca4b29d89ad95154c301479d9c6a95a60a75
BLAKE2b-256 checksum
How to use checksums
805d04d45abbaf557a4b4b6d6a8d88901b522168b902804d4795c2339ffd3d93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / simple_releaser-0.4.0-py3-none-any.whl

Download URL simple_releaser-0.4.0-py3-none-any.whl
Size 62.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5a2c9e91cdd14916b94a9089849449273fd15755039df2102216c1e5b1eba5ca
BLAKE2b-256 checksum
How to use checksums
b36942505d44077148bb692710af846f98b4a61b3a2f3470197c62f2a78706b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Security for simple-releaser 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page