readme-renderer
raw JSON → 44.0 verified Tue May 12 auth: no python install: verified
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).
pip install readme-renderer Common errors
error ModuleNotFoundError: No module named 'readme_renderer' ↓
cause The `readme-renderer` package is not installed in your current Python environment.
fix
pip install readme-renderer
error README rendered too large ↓
cause 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.
error Cannot include non-existent file ↓
cause 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. error <string>:x: (ERROR/3) Unknown directive type "code-block". ↓
cause 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. Warnings
breaking The 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`.
breaking The `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]`.
breaking Support 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.
gotcha reStructuredText 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.
gotcha The 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.
Install
pip install readme-renderer[md] Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) readme-renderer wheel - 0.17s 33.5M
3.10 alpine (musl) readme-renderer - - 0.14s 33.5M
3.10 alpine (musl) md wheel - 0.16s 36.1M
3.10 alpine (musl) md - - 0.15s 36.1M
3.10 slim (glibc) readme-renderer wheel 2.4s 0.14s 34M
3.10 slim (glibc) readme-renderer - - 0.14s 34M
3.10 slim (glibc) md wheel 2.9s 0.14s 36M
3.10 slim (glibc) md - - 0.15s 36M
3.11 alpine (musl) readme-renderer wheel - 0.16s 36.9M
3.11 alpine (musl) readme-renderer - - 0.18s 36.9M
3.11 alpine (musl) md wheel - 0.17s 39.8M
3.11 alpine (musl) md - - 0.18s 39.8M
3.11 slim (glibc) readme-renderer wheel 2.6s 0.15s 37M
3.11 slim (glibc) readme-renderer - - 0.14s 37M
3.11 slim (glibc) md wheel 2.9s 0.15s 40M
3.11 slim (glibc) md - - 0.14s 40M
3.12 alpine (musl) readme-renderer wheel - 0.17s 28.6M
3.12 alpine (musl) readme-renderer - - 0.18s 28.6M
3.12 alpine (musl) md wheel - 0.18s 31.4M
3.12 alpine (musl) md - - 0.17s 31.4M
3.12 slim (glibc) readme-renderer wheel 2.4s 0.17s 29M
3.12 slim (glibc) readme-renderer - - 0.17s 29M
3.12 slim (glibc) md wheel 2.8s 0.18s 32M
3.12 slim (glibc) md - - 0.17s 32M
3.13 alpine (musl) readme-renderer wheel - 0.12s 28.4M
3.13 alpine (musl) readme-renderer - - 0.12s 28.2M
3.13 alpine (musl) md wheel - 0.12s 31.2M
3.13 alpine (musl) md - - 0.13s 31.1M
3.13 slim (glibc) readme-renderer wheel 2.4s 0.12s 28M
3.13 slim (glibc) readme-renderer - - 0.13s 28M
3.13 slim (glibc) md wheel 2.9s 0.12s 32M
3.13 slim (glibc) md - - 0.12s 31M
3.9 alpine (musl) readme-renderer wheel - 0.06s 32.9M
3.9 alpine (musl) readme-renderer - - 0.07s 32.9M
3.9 alpine (musl) md wheel - 0.06s 36.3M
3.9 alpine (musl) md - - 0.07s 36.2M
3.9 slim (glibc) readme-renderer wheel 2.8s 0.05s 33M
3.9 slim (glibc) readme-renderer - - 0.05s 33M
3.9 slim (glibc) md wheel 3.5s 0.06s 37M
3.9 slim (glibc) md - - 0.05s 37M
Imports
- render
from readme_renderer.markdown import render as render_markdown - render
from readme_renderer.rst import render as render_rst
Quickstart last tested: 2026-04-24
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)