---
id: sphinxcontrib-towncrier
version: "0.5.0a0"
license: BSD 3-Clause License
license_treatment: permissive
maintenance: active
---

# sphinxcontrib-towncrier — An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version

License: permissive · Maintenance: active · Downloads: 163.1K/mo

## What it is and what it does

sphinxcontrib-towncrier is a Sphinx extension that bridges Sphinx documentation builds with Towncrier, a changelog management tool. It provides an RST directive that automatically renders a draft changelog containing unreleased fragments into your documentation. The extension reads your project's towncrier configuration and injects the generated changelog at build time, allowing you to display work-in-progress release notes alongside your main documentation.

The package has two runtime dependencies: sphinx and towncrier. It supports Python 3.9 through 3.13 and is classified as alpha-stage software. The extension offers configurable version title generation modes (draft, sphinx-version, or sphinx-release) and allows you to override the title with custom text. It's used by projects like ansible/pylibssh and pypa/pip to keep changelog drafts visible during documentation builds.

Use it for:

- Display unreleased changelog fragments in your project's documentation site during development.
- Automatically generate a draft release notes section in Sphinx docs without manual maintenance.
- Keep contributors and users informed of upcoming changes by embedding the towncrier draft in your docs.
- Integrate changelog management into your Sphinx build pipeline for single-source documentation.
- Override auto-generated version titles with custom release labels or status markers in the changelog.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Sphinx extension that automatically injects a Towncrier-generated changelog draft into documentation, displaying unreleased project version fragments.

Yes, if you use both Sphinx and Towncrier for your project. The extension solves a real integration gap and is actively maintained. However, note that it is still alpha-stage software (version 0.5.0a0), so expect potential API changes. Install it when you want unreleased changelog fragments visible in your documentation builds without manual duplication.

## Install

pip install sphinxcontrib-towncrier
uv add sphinxcontrib-towncrier
poetry add sphinxcontrib-towncrier

## Installing sphinxcontrib-towncrier

Before you install: Low install friction with only two runtime dependencies (sphinx and towncrier). Actively maintained with a recent release in February 2025 and ongoing repository activity.

License in practice: BSD 3-Clause License is permissive, allowing commercial and private use with minimal restrictions beyond attribution and liability disclaimers.

Quickstart:

pip install sphinxcontrib-towncrier

# In conf.py:
extensions = ['sphinxcontrib.towncrier.ext']
towncrier_draft_autoversion_mode = 'draft'
towncrier_draft_working_directory = PROJECT_ROOT_DIR

# In changelog.rst:
.. towncrier-draft-entries::

Requires towncrier to be pre-configured in your project's pyproject.toml; the extension reads towncrier's configuration from that file.

Verify before relying:

- Whether the alpha version (0.5.0a0) is stable enough for production documentation builds.
- Performance characteristics when handling large numbers of changelog fragments.
- Compatibility with custom towncrier fragment types beyond the defaults.

## Package facts

- License: BSD 3-Clause License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 163.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx changelog directive, towncrier sphinx integration, unreleased changelog in docs, sphinx extension documentation, towncrier draft entries, changelog fragment injection, sphinx documentation automation, sphinx-extension, changelog-management, documentation-automation

[View on SkillFed](https://skillfed.io/packages/sphinxcontrib-towncrier) · [View on PyPI](https://pypi.org/project/sphinxcontrib-towncrier/)