---
id: sphinx-pyproject
version: "0.3.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# sphinx-pyproject — Move some of your Sphinx configuration into pyproject.toml

License: permissive · Maintenance: active · Downloads: 167.2K/mo

## What it is and what it does

sphinx-pyproject is a Sphinx extension that reads your documentation configuration from pyproject.toml instead of requiring everything in conf.py. It parses the standard PEP 621 [project] table for basic metadata (name, version, description, authors) and reads additional Sphinx settings from a [tool.sphinx-pyproject] table, then injects those values into your conf.py namespace. This lets you consolidate project metadata in one place and avoid duplicating version numbers and author information across files.

The package provides a SphinxConfig class that acts as both a configuration loader and a Mapping interface, so you can read values, override them programmatically (useful for dynamic version injection), or append to lists like extensions. It's designed for projects that want to follow PEP 621 conventions and reduce boilerplate in their documentation setup.

Use it for:

- Consolidate project name, version, and author metadata in pyproject.toml so Sphinx reads it without duplication
- Inject dynamic version numbers into Sphinx config at build time using config_overrides parameter
- Migrate an existing Sphinx project to PEP 621 structure while keeping conf.py minimal and readable
- Manage Sphinx extensions and settings in a centralized [tool.sphinx-pyproject] table for easier maintenance
- Avoid manual synchronization of author and project details between pyproject.toml and conf.py

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Loads Sphinx documentation configuration from pyproject.toml instead of keeping it all in conf.py, using PEP 621 project metadata and custom tool settings.

Yes, if you use Sphinx and want to follow PEP 621 conventions. The package is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem—keeping project metadata in one place. The 1092 days since last release is not a concern given the recent repository activity and the narrow, stable scope of the tool.

## Install

pip install sphinx-pyproject
uv add sphinx-pyproject
poetry add sphinx-pyproject

## Installing sphinx-pyproject

Before you install: Low install friction with only two runtime dependencies (dom-toml and domdf-python-tools). Repository is active with a recent commit on 2026-07-06, though the last release was 2023-08-18.

License in practice: MIT license is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you retain the license notice.

Quickstart:

# Install
python -m pip install sphinx-pyproject

# In conf.py
from sphinx_pyproject import SphinxConfig

config = SphinxConfig("../pyproject.toml", globalns=globals())

# Configuration values from pyproject.toml are now available

Requires Python 3.6 or later; your pyproject.toml must contain [project] table (PEP 621) with name, version, description, and author/maintainer fields, plus optional [tool.sphinx-pyproject] for additional Sphinx settings.

Verify before relying:

- Whether dom-toml and domdf-python-tools are stable and well-maintained (not stated in fact sheet)
- How well this integrates with Sphinx extensions that modify conf.py dynamically
- Performance impact when loading large or complex pyproject.toml files

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 167.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx configuration in pyproject.toml, move sphinx config to pyproject, pep 621 sphinx setup, sphinx conf.py pyproject, sphinx configuration loader, toml sphinx config, sphinx pyproject integration, pep-621, sphinx-config, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/sphinx-pyproject) · [View on PyPI](https://pypi.org/project/sphinx-pyproject/)