---
id: towncrier
version: "25.8.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# towncrier — Building newsfiles for your project.

License: permissive · Maintenance: active · Downloads: 4.6M/mo

## What it is and what it does

Towncrier is a changelog generator that collects small, issue-specific "news fragments" from developers and synthesizes them into a polished changelog for end users. Rather than having all developers edit a single changelog file (which causes merge conflicts) or mining the Git history (which mixes implementation details with user-facing changes), towncrier asks each contributor to create a small fragment file describing their change from a user perspective. The tool then combines these fragments into a structured, readable release note.

It works as a command-line tool and integrates with any project type and platform. The core dependencies are minimal: click for CLI handling, jinja2 for templating the output, and importlib utilities for metadata. It supports Python 3.9 through 3.13 and is used by major projects.

Use it for:

- Generate a changelog for a release by collecting pre-written fragments from each merged pull request or closed issue.
- Avoid merge conflicts on a shared changelog file by having each contributor write a separate fragment instead.
- Produce user-focused release notes that omit implementation details and focus on what end users need to know.
- Automate changelog creation as part of a release workflow or CI/CD pipeline.
- Maintain a consistent changelog format and structure across multiple releases.

## Worth the install?

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

Towncrier generates changelogs from individual news fragment files rather than a single shared log, reducing merge conflicts and focusing on end-user-relevant changes.

Yes. Towncrier solves a real problem—changelog merge conflicts and scattered release-note authorship—with a lightweight, well-maintained tool. Low install friction, no known vulnerabilities, active development, and proven adoption make it a safe choice for any team managing releases.

## Install

pip install towncrier
uv add towncrier
poetry add towncrier

## Installing towncrier

Before you install: Low install friction with a pure-Python wheel and five common dependencies (click, jinja2, importlib-metadata, importlib-resources, tomli). Actively maintained with recent commits and no known vulnerabilities.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute towncrier freely provided you retain the license notice.

Quickstart:

pip install towncrier
towncrier build --version 25.8.0

Requires Python 3.9 or later; auto-detection of project version may require additional configuration depending on your project setup.

Verify before relying:

- Whether the tool's auto-detection of project version works reliably across all project types and build systems.
- Performance characteristics when handling large numbers of news fragments or complex fragment templates.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

changelog generator, news fragment management, automated release notes, changelog from fragments, project changelog tool, newsfile builder, release notes automation, release-management, changelog-automation

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