Registry / web-framework / readme-renderer

readme-renderer

library45.0pypypi✓ verified 27d ago

readme-renderer is a Python library designed to safely convert README file content (Markdown, reStructuredText, or plain text) into HTML. It is primarily used by PyPI's Warehouse to render `long_description` for Python packages, ensuring they display correctly and securely on the PyPI website. The library is currently at version 44.0 and is actively maintained by the Python Packaging Authority (PyPA).

web-framework serialization

pip install readme-renderer

github ↗package ↗

INSTALL

IMPORT

SIG · README-RENDERER

readme-renderer

web-frameworkpythonv45.0

Install

2.8s avg

Import

54ms

Disk

35MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v45.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.055s · 36.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.8s · import 0.053s · 36MB

35MB installed

● package 35MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

render

✓ from readme_renderer.markdown import render as render_markdown

render

✓ from readme_renderer.rst import render as render_rst

This quickstart demonstrates how to render both Markdown and reStructuredText content into HTML using the `readme_renderer` library. It imports the specific rendering functions from their respective submodules and then calls them with sample content. The output is a string of HTML. Note that for Markdown rendering, the optional `cmarkgfm` dependency is highly recommended, installed via `pip install readme-renderer[md]`.

from readme_renderer.markdown import render as render_markdown from readme_renderer.rst import render as render_rst # Example Markdown content markdown_content = """ # My Project This is a *great* project with `python` code. ```python def hello_world(): print("Hello, PyPI!") ``` """ # Example reStructuredText content rst_content = """ My Project ========== This is a *great* project with ``python`` code. .. code-block:: python def hello_world(): print("Hello, PyPI!") """ # Render Markdown html_from_markdown = render_markdown(markdown_content) print("--- Rendered Markdown ---") print(html_from_markdown[:200] + '...' if len(html_from_markdown) > 200 else html_from_markdown) # Render reStructuredText # Note: ensure 'docutils' is installed for rST rendering. html_from_rst = render_rst(rst_content) print("\n--- Rendered reStructuredText ---") print(html_from_rst[:200] + '...' if len(html_from_rst) > 200 else html_from_rst)

Debug

Known issues

breakingThe library was originally named `readme` and was renamed to `readme_renderer` to resolve naming conflicts with system files. Users migrating from the old `readme` package must update their imports and dependencies.

fix

Update `pip install` commands and Python import statements from `readme` to `readme_renderer`.

affects: <0.7.0 (renamed in 0.7.0, released 2016-01-04)

breakingThe `cmarkgfm` dependency, essential for Markdown rendering, was moved into an optional extra. If you use `readme-renderer` to process Markdown and do not install it with `[md]` extra, rendering may fail or emit a `UserWarning`.

fix

Install the library with the Markdown extra: `pip install readme-renderer[md]`.

affects: >=22.0 (released 2018-09-17)

breakingSupport for Python 3.7 was dropped. Users on older Python versions will need to upgrade their Python interpreter or use an older `readme-renderer` version.

fix

Upgrade Python to 3.8 or newer. The current version (44.0) requires Python >=3.9.

affects: >=40.0 (released 2023-06-16)

gotchareStructuredText content must adhere strictly to the Docutils specification without Sphinx extensions (e.g., directives and roles like `:py:func:`). Invalid markup or Sphinx-specific syntax will cause PyPI to display the raw source instead of a rendered version.

fix

Validate reStructuredText carefully, for example, by using `twine check dist/*` on your built distributions, and avoid Sphinx-specific extensions.

affects: All versions

gotchaThe library performs HTML sanitization on the rendered output to prevent XSS attacks. This means only a whitelist of HTML tags and attributes are permitted. Custom or unrecognized HTML within your README may be stripped out.

fix

Review the allowed HTML tags if embedding HTML directly in your README. Generally, rely on Markdown or reStructuredText syntax for formatting rather than raw HTML.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'readme_renderer'

The `readme-renderer` package is not installed in your current Python environment.

fix

pip install readme-renderer

README rendered too large

The rendered HTML output of your README file exceeds PyPI's maximum allowed size (typically 256KB), a limit checked by `readme-renderer` during conversion.

fix

Reduce the size of your README file by simplifying content, removing large images, or optimizing its structure to stay within PyPI's limits.

Cannot include non-existent file

Your reStructuredText (RST) README contains an `.. include::` directive that references a file which does not exist or cannot be found by `docutils`, the parser used by `readme-renderer`.

fix

Ensure that all files referenced by `.. include::` directives exist and are correctly located relative to your README.rst file.

<string>:x: (ERROR/3) Unknown directive type "code-block".

Your reStructuredText (RST) README uses Sphinx-specific directives or roles (like `code-block`) that are not natively supported by standard `docutils`, which `readme-renderer` employs for parsing.

fix

Use standard reStructuredText syntax or directives supported by `docutils`, or switch to Markdown if advanced formatting is essential and Sphinx is not being used for rendering.

Upgrade

Version history

45.0latest on PyPI · released Jun 9, 2026

Audit

Dependencies

docutilsrequiredRequired for rendering reStructuredText content.

nh3requiredUsed for HTML sanitization to prevent Cross-Site Scripting (XSS) vulnerabilities.

pygmentsrequiredUsed for syntax highlighting in rendered code blocks.

cmarkgfmoptionalOptional dependency required for rendering Markdown content.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/pypa/readme_renderer ↗

packagehttps://pypi.org/project/readme-renderer/ ↗