sphinxcontrib-shellcheck
Sphinx extension to lint shell code blocks
Decision gist · record as of 2026-08-14
No. The package is abandoned (last release March 2020) and has not been updated for modern Python or Sphinx versions. While it has low install friction and a permissive MIT license, the lack of maintenance means it will not receive bug fixes, security updates, or compatibility patches. If you need shell linting in Sphinx documentation, consider maintaining a fork or evaluating active alternatives.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- The shellcheck command-line utility must be installed on the system; the package is a Sphinx extension wrapper around it.
- Low install friction with pure Python wheels for Python 3.5, 3.6, 3.7, and 3.8.
- However, the package is abandoned as of March 2020, and depends on the external shellcheck utility which must be installed separately on the system.
License · maintenance · safety
MIT (permissive) — MIT license permits unrestricted use, modification, and distribution with minimal restrictions, making it safe to adopt in most projects.
last release 2020-03-30 (2328 days) · last repo commit 2022-02-17 · 2 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 76,715 downloads/mo, #14,597 on PyPI
Alternatives
Verify before relying
pip install sphinxcontrib-shellcheck
Add to conf.py:
extensions = ["sphinxcontrib.shellcheck"]
Run: sphinx-build -b shellcheck . _build example.rst- Whether shellcheck utility is automatically installed or must be provisioned separately by the user.
- Compatibility with Python versions beyond 3.8 or modern Sphinx versions.
- Current state of the shellcheck executable dependency and any version constraints.
What it is and what it does
sphinxcontrib-shellcheck is a Sphinx documentation builder extension that integrates the shellcheck linter into your documentation build process. It scans bash, sh, dash, and ksh code blocks embedded in reStructuredText files and reports shell script errors, style violations, and potential bugs with line and column references.
The extension runs as a custom Sphinx builder (invoked with `sphinx-build -b shellcheck`) and processes code blocks marked with shell language directives. It relies on the external shellcheck utility to perform the actual linting and outputs violations to both the console and a log file. Configuration options allow you to specify shell dialects, the shellcheck executable path, terminal prompt character, and debug verbosity.
Use it for
- Validate shell scripts embedded in installation guides or deployment documentation before publishing.
- Catch common shell scripting mistakes in code examples during CI/CD documentation builds.
- Enforce consistent shell style across multiple documentation files in a large project.
- Document shell commands with automatic verification that they follow best practices.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
No.
The package is abandoned (last release March 2020) and has not been updated for modern Python or Sphinx versions. While it has low install friction and a permissive MIT license, the lack of maintenance means it will not receive bug fixes, security updates, or compatibility patches. If you need shell linting in Sphinx documentation, consider maintaining a fork or evaluating active alternatives.
Install
sphinxcontrib-shellcheck on PyPI
Before you install
Low install friction with pure Python wheels for Python 3.5, 3.6, 3.7, and 3.8. However, the package is abandoned as of March 2020, and depends on the external shellcheck utility which must be installed separately on the system.
The shellcheck command-line utility must be installed on the system; the package is a Sphinx extension wrapper around it.
License in practice
MIT license permits unrestricted use, modification, and distribution with minimal restrictions, making it safe to adopt in most projects.
Quickstart
pip install sphinxcontrib-shellcheck
Add to conf.py:
extensions = ["sphinxcontrib.shellcheck"]
Run: sphinx-build -b shellcheck . _build example.rstVerify before relying
- Whether shellcheck utility is automatically installed or must be provisioned separately by the user.
- Compatibility with Python versions beyond 3.8 or modern Sphinx versions.
- Current state of the shellcheck executable dependency and any version constraints.
Package facts
| License | MIT permissive |
| Python support | Not specified |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 4 packagesdecoratordocutilssphinxsix |
| Maintenance | Abandoned 2,328 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 76,715 / month, #14,597 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableEnvironment :: ConsoleFramework :: Sphinx :: ExtensionIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseNatural Language :: EnglishOperating System :: OS IndependentProgramming Language :: Python :: 3.5Programming Language :: Python :: 3.6Programming Language :: Python :: 3.7Programming Language :: Python :: 3.8Topic :: Software Development :: Documentation |
Evidence: sphinxcontrib_shellcheck-1.1.2-py35-none-any.whl; sphinxcontrib_shellcheck-1.1.2-py36-none-any.whl; sphinxcontrib_shellcheck-1.1.2-py37-none-any.whl; sphinxcontrib_shellcheck-1.1.2-py38-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “sphinx shell linting”
- sphinxcontrib-shellcheckA Sphinx extension that automatically lints shell code blocks in…
- sphinx-promptSphinx Prompt is a Sphinx extension that renders shell and code…
- esbonioA Language Server Protocol implementation for reStructuredText and…
Give your agent the search over MCP, or paste the wish link into any chat.
More Documentation packages
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
Converts Markdown text to HTML using a Python implementation of John Gruber's Markdown specification, with support for extensions.
Install it if you need to parse Markdown in Python.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
Griffe extracts the complete structure and signatures of Python programs to generate API documentation or detect breaking changes in your project's public API.
Install it if you need to programmatically inspect Python code structure, generate API docs, or enforce API stability in CI.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
Material for MkDocs is a professional theme and extension for MkDocs that transforms Markdown documentation into a responsive, searchable static site with minimal configuration.
Install it if you need to publish Markdown-based documentation as a professional static site without writing custom HTML or CSS.
See also sphinx-markdown-builder · sphinx-lint · linuxdoc · sphinxcontrib-spelling · shellcheck-py · sphinx-substitution-extensions · rstcheck · sphinx-jinja · sphinxcontrib-confluencebuilder · sphinx-llm