keepachangelog

What it is and what it does

keepachangelog is a Python library and command-line tool for working with changelog files that follow the Keep a Changelog format. It parses markdown changelogs into structured Python dictionaries, allowing you to read, modify, and regenerate changelog content programmatically. The library can extract release information including version numbers, dates, semantic versioning metadata, and categorized change entries (Added, Changed, Fixed, Deprecated, Removed, Security).

The package is designed for two main workflows: reading existing changelogs to extract release data for automation (such as generating GitHub release bodies), and automating changelog maintenance during development—particularly creating new releases by moving unreleased entries into versioned sections and automatically incrementing version numbers based on change types. It includes both a Python API and a command-line interface, making it suitable for CI/CD pipelines and manual changelog management.

Use it for:

• Automate release workflows in CI/CD by parsing changelog entries and generating release notes for GitHub or GitLab
• Programmatically bump version numbers based on changelog content (breaking changes increment major, features increment minor, fixes increment patch)
• Convert changelog markdown into structured data for documentation sites or release management systems
• Validate that changelog entries follow Keep a Changelog format before merging pull requests
• Retrieve raw changelog content for a specific version to populate release body templates

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parse, manipulate, and generate changelog files in Keep a Changelog format, converting between markdown and Python dictionaries, and automating semantic version releases.

Yes. The package has zero runtime dependencies, permissive MIT licensing, active maintenance, and fills a specific need for teams using Keep a Changelog format. Install it if you maintain a changelog and want to automate release workflows or programmatically access changelog data; skip it if you manage changelogs manually without automation.

Install

keepachangelog on PyPI

pip install keepachangelog

uv add keepachangelog

poetry add keepachangelog

Installing keepachangelog

Before you install

Low friction install with no runtime dependencies. Active maintenance with recent commits; last release was over a year ago but the repository remains current.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal obligations—suitable for any project type.

Quickstart

import keepachangelog

# Parse changelog to dict
changes = keepachangelog.to_dict("CHANGELOG.md")
print(changes["1.0.0"]["metadata"]["version"])

# Create a new release
new_version = keepachangelog.release("CHANGELOG.md")

Requires Python 3.9 or later; changelog file must follow Keep a Changelog format with proper markdown structure.

Verify before relying

• Whether the REST API endpoint integrations (Starlette, Flask-RestX) are fully functional or still in development
• Performance characteristics when parsing very large changelog files

Package facts

Evidence: keepachangelog-2.0.0-py3-none-any.whl

Keywords: changelog, CHANGELOG.md, markdown

Tags

More Build Tools packages