Sphinx Issues

6.0.0 · active · verified Thu Apr 16

Sphinx Issues is a Sphinx extension designed to facilitate linking to a project's issue tracker directly within reStructuredText documentation. It provides roles for creating links to issues, pull requests, user profiles, and commits, with built-in support for GitHub and flexible configuration for other platforms like GitLab. The current version is 6.0.0, released on March 13, 2026, and it maintains an active development and release cadence.

Common errors

```
Unknown interpreted text role 'issue'
```
cause The `sphinx_issues` extension has not been correctly added to the `extensions` list in `conf.py`, or Sphinx cannot find the `sphinx_issues` module.

fix Verify that `sphinx_issues` is included in the `extensions` list within your `conf.py` file: `extensions = ['sphinx_issues', ...]`. Ensure `sphinx-issues` is installed in your environment.
```
Sphinx build warning: Issues configuration (issues_github_path or issues_default_group_project) not found. Issue/PR roles may not generate correct URLs.
```
cause For GitHub projects, the `issues_github_path` variable is missing or incorrectly configured in `conf.py` after upgrading to `sphinx-issues` 6.0.0.

fix Add `issues_github_path = 'YOUR_GITHUB_USER_OR_ORG/YOUR_REPO_NAME'` to your `conf.py`. For other issue trackers, explicitly define `issues_uri` and related `issues_pr_uri`, etc.
```
AttributeError: module 'sphinx_issues' has no attribute '__version__'
```
cause Attempting to access `__version__`, `__author__`, or `__license__` directly from the `sphinx_issues` module after upgrading to version 6.0.0. These attributes were removed in this version.

fix Use `importlib.metadata.version('sphinx-issues')` to programmatically retrieve the installed version, and similarly for other metadata.

Warnings

breaking Version 6.0.0 removes implicit extraction of the group/project from GitHub URLs when `issues_uri` is set. You must now explicitly define `issues_github_path` or `issues_default_group_project` for GitHub projects, or fully specify `issues_uri` and related paths for custom trackers.
Fix: In `conf.py`, set `issues_github_path = 'your_github_user_or_org/your_repo_name'` for GitHub, or explicitly define `issues_uri`, `issues_pr_uri`, `issues_commit_uri`, and `issues_user_uri` for other services.
breaking As of version 5.0.0, the `:cwe:` and `:cve:` roles were removed from `sphinx-issues` because these roles are now officially included in Sphinx >= 8.1. If you are using Sphinx < 8.1 and still require these roles, you must pin `sphinx-issues` to a version less than 5 (`sphinx-issues<5`).
Fix: Upgrade Sphinx to version 8.1 or higher. If upgrading Sphinx is not an option, downgrade `sphinx-issues` to `<5.0.0`.
gotcha sphinx-issues v6.0.0 officially supports Python 3.10-3.14. Python 3.9 and older versions are no longer supported. Ensure your project's Python environment meets this requirement to avoid installation or runtime issues.
Fix: Upgrade your Python environment to 3.10 or newer. If you must use Python 3.9 or older, you will need to use an older version of `sphinx-issues` (e.g., `<6.0.0`).
gotcha `sphinx-issues` version 6.0.0 requires Sphinx version 8.1.0 or newer. Installing `sphinx-issues` v6.0.0 with an older Sphinx version may lead to unexpected behavior or build errors.
Fix: Ensure your Sphinx installation is `sphinx>=8.1.0`. Update Sphinx using `pip install -U sphinx` or specify the version in your `requirements.txt`.

Install

pip install sphinx-issues Install latest version

Imports

sphinx_issues
```
extensions = ['sphinx_issues']
```
sphinx-issues is enabled as a Sphinx extension by adding its module name to the 'extensions' list in your project's conf.py file.

Quickstart

To quickly integrate `sphinx-issues`, first install it via pip. Then, add `'sphinx_issues'` to the `extensions` list in your Sphinx project's `conf.py`. For GitHub projects, configure `issues_github_path` to specify your repository. This enables the `:issue:`, `:pr:`, `:commit:`, and `:user:` roles in your reStructuredText files.

# conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'

extensions = [
    'sphinx_issues'
]

# Required for GitHub integration
# Replace 'sloria/marshmallow' with your project's GitHub path (user/repo or org/repo)
issues_github_path = 'sloria/marshmallow'

# Example usage in an .rst file:
# See issue :issue:`42`
# See PR :pr:`58`
# Thanks to :user:`bitprophet`
# Fixed in :commit:`6bb9124d5e9dbb2f7b52864c3d8af7feb1b69403`

view raw JSON →