Install & Compatibility
Where this runs
tested against v0.3.2 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.3s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxemoji
✓ extensions = ['sphinxemoji.sphinxemoji'] # In conf.py
✗ import sphinxemoji # Not directly imported in Python code
sphinxemoji is enabled as a string in Sphinx's conf.py configuration, not directly imported as a Python module in your project's code.
To quickly enable `sphinxemoji`, add `'sphinxemoji.sphinxemoji'` to your `extensions` list in `conf.py`. Then, you can use emoji shortcodes wrapped in bars (e.g., `|:smile:|`) directly in your reStructuredText or MyST files. An optional `sphinxemoji_style` configuration can be added to `conf.py` to use a consistent emoji set like Twemoji.
# conf.py
extensions = [
'sphinxemoji.sphinxemoji',
]
# Your RST or MyST file (e.g., index.rst or index.md)
# This text includes a smiley face |:smile:| and a snake too! |:snake:|
# Don't you love it? |:heart_eyes:|
# Optional: Set a consistent emoji style (e.g., Twemoji)
# sphinxemoji_style = 'twemoji'
Debug
Known issues
breakingsphinxemoji version 0.3.2 (and earlier) is incompatible with Sphinx v9 due to changes in `SphinxComponentRegistry.create_source_parser`.fixCheck for an updated version of sphinxemoji that explicitly supports Sphinx v9. If unavailable, pin your Sphinx dependency to a version prior to 9.x (e.g., `pip install Sphinx<9`).
affects: 0.3.2 and older
gotchaBuilding documentation to PDF via LaTeX can result in `inputenc Error: Unicode character ... not set up for use with LaTeX` if your LaTeX distribution or configuration does not properly handle Unicode emojis.fixConfigure Sphinx to use a Unicode-aware LaTeX engine (e.g., XeLaTeX or LuaLaTeX) by setting `latex_engine` in `conf.py`, or ensure your LaTeX preamble includes packages for Unicode support. Alternatively, consider setting `sphinxemoji_style = 'twemoji'` to render emojis as images, which are generally more compatible with LaTeX.
affects: All versions
gotchaUsers on Windows might encounter `encoding` errors when `sphinxemoji.py` attempts to load its `codes.json` file.fixThis issue might require a manual modification to the `sphinxemoji.py` file in your `site-packages` directory to specify UTF-8 encoding when opening the JSON file. (e.g., `open(..., encoding='utf-8')`).
affects: Potentially all versions
Upgrade
Version history
0.3.2latest on PyPI · released Dec 15, 2025
Audit
Dependencies
SphinxrequiredCore documentation generator that sphinxemoji extends.
PythonoptionalRequires Python 3.9 or higher for installation.