---
id: sphinx-remove-toctrees
version: "1.0.0.post1"
license: MIT License Copyright (c) 2018 Chris Holdgraf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: dormant
---

# sphinx-remove-toctrees — Reduce your documentation build size by selectively removing toctrees from pages.

License: permissive · Maintenance: dormant · Downloads: 147.9K/mo

## What it is and what it does

sphinx-remove-toctrees is a Sphinx extension that speeds up documentation builds by removing toctree objects from pages you specify. It works by intercepting Sphinx's build process after the initial validation phase but before HTML rendering, selectively deleting toctree entries that match glob-like patterns you configure in conf.py. This is most useful when your documentation uses autosummary to generate many stub pages—each one adds overhead to the build, especially in themes that render the entire table of contents on every page.

You configure it by adding a list of glob patterns to a `remove_from_toctrees` key in conf.py, specifying which pages should be removed from the sidebar. The extension ensures no warnings are raised about missing files while still removing them from the rendered navigation, avoiding the link-resolution overhead that slows large builds.

Use it for:

- Speed up Sphinx builds for projects with auto-generated API documentation using autosummary
- Remove stub pages from sidebar navigation without triggering missing-file warnings
- Optimize documentation rendering for themes with collapsible sidebar sections
- Reduce build time for large nested documentation hierarchies
- Selectively hide generated API pages from table of contents while keeping them accessible

## Worth the install?

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

A Sphinx extension that selectively removes toctree objects from specified pages to reduce documentation build time, particularly for projects with large auto-generated API documentation.

Yes, if you maintain Sphinx documentation with large auto-generated API sections and experience slow builds. The extension is straightforward to configure, has no complex dependencies, and solves a specific performance problem. The dormant maintenance status is acceptable for a focused, stable tool—no active vulnerabilities and it supports current Python versions.

## Install

pip install sphinx-remove-toctrees
uv add sphinx-remove-toctrees
poetry add sphinx-remove-toctrees

## Installing sphinx-remove-toctrees

Before you install: Low friction: pure Python wheel with only sphinx as a runtime dependency. Maintenance is dormant—last release was 875 days ago, though the repository remains active and unarchived.

License in practice: MIT License permits unrestricted use, modification, and distribution with minimal restrictions, making it safe for both open-source and commercial projects.

Quickstart:

pip install sphinx-remove-toctrees

In conf.py:
extensions.append("sphinx_remove_toctrees")
remove_from_toctrees = ["api/generated/*", "subfolder/page_two.rst"]

Verify before relying:

- Performance improvement magnitude for typical documentation projects with large API docs
- Compatibility with specific Sphinx themes beyond those mentioned in the description

## Package facts

- License: MIT License Copyright (c) 2018 Chris Holdgraf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 147.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx build performance optimization, remove toctree sidebar links, sphinx documentation speed, api documentation build time, sphinx extension toctree, reduce sphinx build size, autosummary page optimization, sphinx-extension, build-optimization, documentation

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