towncrier

Building newsfiles for your project.

towncrier v25.8.0 4.6M downloads/30d#2,282 on PyPI★ 914

Permissive license MIT Active released 2025-08-30

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 on this page — 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

towncrier on PyPI

pip

pip install towncrier

uv

uv add towncrier

poetry

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 the current Python release (>=3.9)
Install friction	low — pure-Python wheel
Runtime dependencies	5 — click, importlib-metadata, importlib-resources, jinja2, tomli
Maintenance	actively maintained — 349 days since the last release
Last repo commit	2026-08-04
First released	2015-12-27
Downloads	4,555,801/month — #2,282 on PyPI (30-day window, as of 2026-08-14)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-14)

Evidence: towncrier-25.8.0-py3-none-any.whl

Intended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseOperating System :: MacOS :: MacOS XOperating System :: Microsoft :: WindowsOperating System :: POSIX :: LinuxProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.9Programming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPy