How to keep a changelog for a Python package on PyPI

Add your changelog to [project.urls]. PyPI shows these URLs as project links on the package page, and the well-known project URLs specification recognises a Changelog label (with aliases such as ‘What's New’ and ‘History’) and a separate Release Notes label, so tools know which link is which.

[project]
name = "mylib"
version = "2.0.0"
requires-python = ">=3.10"

[project.urls]
Homepage = "https://example.com"
Documentation = "https://example.com/docs"
Repository = "https://github.com/OWNER/REPO"
Changelog = "https://github.com/OWNER/REPO/blob/main/CHANGELOG.md"

Python versions follow PEP 440: pre-releases look like 2.0.0a1, 2.0.0b2 or 2.0.0rc1, post-releases like 2.0.0.post1 and development releases like 2.0.0.dev3. pip ignores pre-releases and development releases unless you pass --pre or a specifier that includes one (such as >=2.0.0rc1), so a release candidate won't reach people by accident.

Give each pre-release its own changelog entry, then let the final release's entry summarise everything since the last stable version.

If a release is broken, yank it on PyPI. Under PEP 592, installers ignore a yanked release unless it's pinned exactly with == or ===, so pinned installs keep working while new installs skip it. Deleting a release can't be undone, and PyPI won't let you upload a file with the same name again.

Keep the entry in your changelog and mark it with [YANKED] after the date, plus one line saying why and which version to use instead. Keep a Changelog 2.0.0 is blunt about it: “List it; do not hide it.”

Raise requires-python in the release that drops support. pip compares it with the running interpreter and picks the newest release that still supports it, so people on the old Python quietly stay on your previous version (see the Python Packaging guide). Mark the entry **Breaking:** in the changelog anyway: people who pin versions or build from source still need to know.

Emit a DeprecationWarning from anything you plan to remove, and name the replacement in the message. Python hides DeprecationWarning by default except in code run directly as __main__ (PEP 565), but pytest shows it by default, which is where many of your users will see it.

import warnings

def fetch_sync(url):
    warnings.warn(
        "fetch_sync() is deprecated and will be removed in 3.0.0; "
        "use asyncio.run(client.fetch(url)) instead.",
        DeprecationWarning,
        stacklevel=2,
    )
    ...

# Python 3.13+: the decorator also tells type checkers (PEP 702).
# On older versions: from typing_extensions import deprecated
from warnings import deprecated

@deprecated("Use asyncio.run(client.fetch(url)); removal planned for 3.0.0.")
def fetch_sync(url): ...

Then list it under Deprecated in the changelog with the replacement and the planned removal version. More in how to write deprecation notices.

On a project with many contributors, merge conflicts in CHANGELOG.md get old fast. towncrier has each pull request add a small ‘news fragment’ file; at release time it assembles them into the changelog and removes the fragments. pip uses it: fragments go in a news/ directory and are compiled into NEWS.rst.

# pyproject.toml
[tool.towncrier]
directory = "changes"
filename = "CHANGELOG.md"

# In a pull request: add one fragment per change
towncrier create 123.feature.md --content "parse() accepts pathlib.Path objects."

# At release time: build the changelog section for the new version
towncrier build --version 2.1.0