Registry /
devops / python-semantic-release
Install & Compatibility
Where this runs
tested against v10.6.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 52.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.7s · import 0.000s · 52MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main
✓ from semantic_release.cli import main
✗ from semantic_release.cli import main
This quickstart demonstrates how to programmatically invoke the `semantic-release` CLI using `subprocess.run` in Python. It sets up a temporary Git repository and a minimal `pyproject.toml` to make the `semantic-release publish --dry-run` command runnable in isolation. The primary way to use `python-semantic-release` is via its `semantic-release` CLI command, typically integrated into CI/CD pipelines. Ensure your project has a properly configured `pyproject.toml` and a suitable Git history for real releases.
import subprocess
import os
import shutil
def run_semantic_release_demo():
# Setup a temporary directory for the demo
demo_dir = "semantic_release_demo"
if os.path.exists(demo_dir):
shutil.rmtree(demo_dir)
os.makedirs(demo_dir)
os.chdir(demo_dir)
try:
# 1. Initialize a Git repository
subprocess.run(['git', 'init', '-b', 'main'], check=True, capture_output=True)
subprocess.run(['git', 'config', 'user.email', 'test@example.com'], check=True, capture_output=True)
subprocess.run(['git', 'config', 'user.name', 'Test User'], check=True, capture_output=True)
# 2. Create a minimal pyproject.toml for configuration
pyproject_content = '''
[tool.semantic_release]
branch = "main"
version_source = "tag"
changelog_file = "CHANGELOG.md"
'''
with open("pyproject.toml", "w") as f:
f.write(pyproject_content)
# 3. Add some initial content and commit
with open('README.md', 'w') as f:
f.write('# My Project\n\nThis is a demo project.')
subprocess.run(['git', 'add', 'README.md', 'pyproject.toml'], check=True, capture_output=True)
subprocess.run(['git', 'commit', '-m', 'feat: Initial commit and project setup'], check=True, capture_output=True)
print("Successfully set up demo Git repository and pyproject.toml.\n")
# 4. Run semantic-release in dry-run mode
print("--- Running semantic-release publish (dry run) ---")
result = subprocess.run(
['semantic-release', 'publish', '--dry-run'],
capture_output=True,
text=True,
check=True
)
print("STDOUT:\n", result.stdout)
print("STDERR:\n", result.stderr)
print("\nSemantic Release Dry Run completed successfully! Above is the simulated output.")
print("\nTo perform a real release, remove '--dry-run' and ensure a remote Git repository is configured.")
except subprocess.CalledProcessError as e:
print(f"Error during semantic-release demo: {e}")
print("STDOUT:\n", e.stdout)
print("STDERR:\n", e.stderr)
finally:
os.chdir('..')
shutil.rmtree(demo_dir, ignore_errors=True)
print(f"\nCleaned up temporary directory: {demo_dir}")
if __name__ == '__main__':
run_semantic_release_demo()
semantic-release --version
Debug
Known issues
breakingConfiguration was fully moved from legacy files like `release.config.json` or `setup.cfg` to `pyproject.toml`. Older configuration files are no longer parsed.fixMigrate your project configuration to the `[tool.semantic_release]` section in `pyproject.toml`. Refer to the official documentation for the updated syntax and options.
affects: < 8.0.0 (migration to >= 8.0.0)
breakingPython 3.7 support has been officially dropped. The library now requires Python 3.8 or newer.fixUpgrade your Python environment to version 3.8 or a later compatible version.
affects: >= 10.0.0
breakingThe configuration option `commit_parser` was renamed to `commit_analyzer` in `pyproject.toml`.fixUpdate your `pyproject.toml` file to use `commit_analyzer` instead of `commit_parser` under the `[tool.semantic_release]` section.
affects: >= 10.0.0
gotchaShallow Git clones in CI/CD pipelines (e.g., `fetch-depth: 1` in GitHub Actions checkout) can prevent `semantic-release` from accessing full commit history or older tags, leading to incorrect version calculations or failures.fixConfigure your CI/CD pipeline to perform a full Git clone (e.g., `fetch-depth: 0` for GitHub Actions `checkout` action) to ensure all necessary history and tags are available.
affects: All versions
gotchaIncorrectly configured `version_source` or `version_variable` paths can cause `semantic-release` to fail finding or updating the project's version string.fixVerify that `version_source` (e.g., `tag`, `file`) is correctly set in `pyproject.toml`. If using `file`, ensure `version_variable` specifies the exact relative path to the file and the name of the variable (e.g., `src/my_package/__init__.py:__version__`).
affects: All versions
Upgrade
Version history
10.6.2latest on PyPI · released Aug 28, 2026
Audit
Dependencies
No dependency data recorded yet.