---
id: changelog
version: "0.6.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# changelog — Provides simple Sphinx markup to render changelog displays.

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

## What it is and what it does

Changelog is a Sphinx extension that provides markup directives to structure and render changelog entries in documentation. It lets you organize changes by version, tag them by category, and link to tickets, pull requests, and changesets. The extension groups and sorts changes according to configuration, supporting both simple tags and compound tags that match multiple categories.

The package is used by SQLAlchemy and related projects. It is marked experimental but appears stable in practice. It depends on Sphinx, docutils, and looseversion, and runs as a pure Python wheel with no compiled dependencies. The extension also supports advanced features like importing changes from multiple files, rendering to markdown, and a command-line tool for gathering per-file changelog entries at release time.

Use it for:

- Organize release notes by version and category in Sphinx-based project documentation.
- Link changelog entries to tickets, pull requests, and changesets using configurable URL templates.
- Group related changes under compound tags to show hierarchical change categories.
- Import changelog entries from multiple .rst files to enable per-file change tracking during development.
- Generate markdown changelogs from reStructuredText for use in GitHub releases or web GUIs.

## Worth the install?

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

A Sphinx extension that generates formatted changelog displays from reStructuredText markup, organizing changes by version, tags, and sections.

Yes, if you maintain a Sphinx-based project and want structured changelog markup. The extension is actively maintained, has no security vulnerabilities, and low install friction. The MIT license is permissive. The main caveat is that it is marked experimental and has a small user base, so community support is limited—verify compatibility with your Sphinx version before committing.

## Install

pip install changelog
uv add changelog
poetry add changelog

## Installing changelog

Before you install: Low install friction; pure Python wheel with three runtime dependencies (Sphinx, docutils, looseversion). Actively maintained with no known vulnerabilities.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and proprietary projects.

Quickstart:

# Install
pip install changelog

# In conf.py, add to extensions list:
extensions = ['changelog']

# In your .rst file, use the directive:
# .. changelog::
#     :version: 1.5.6
#     :released: Sun Oct 12 2008
#
#     .. change::
#         :tags: general
#         :tickets: 27
#
#       Description of the change.

Requires Sphinx to be installed and a Sphinx documentation project configured.

Verify before relying:

- Whether the package works with current Sphinx versions or has known compatibility issues with recent releases.
- Whether the experimental status noted in the description means breaking changes are likely or if it is stable in practice.
- What specific Python versions are supported beyond the general Python 3 classifier.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 129.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx changelog extension, generate changelog from rst, sphinx documentation changelog, release notes generator sphinx, version history markup, changelog sections tags, sphinx change directive, sphinx-extension, release-notes, documentation-generation

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