---
id: keepachangelog
version: "2.0.0"
license: MIT License Copyright (c) 2024 Colin Bounouar Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# keepachangelog — Manipulate keep a changelog files

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

## 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 above — 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

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

- License: MIT License Copyright (c) 2024 Colin Bounouar Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 195.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

keep a changelog parser, changelog markdown manipulation, semantic version release automation, changelog to dict conversion, CHANGELOG.md editor, changelog-automation, semantic-versioning

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