pureshellcheck

A pure Python reimplementation of ShellCheck's most common checks. No binaries, no Haskell runtime, no compilation — pip install pureshellcheck and it works anywhere Python runs, including AWS Lambda, Pyodide/WASM, and locked-down CI sandboxes where you can't install the real ShellCheck binary.

$ pip install pureshellcheck
$ pureshellcheck deploy.sh

In deploy.sh line 8:
rm -rf $BUILD_DIR/*
       ^--------^ SC2086 (info): Double quote to prevent globbing and word splitting.

Why

• Agent & tooling friendly. LLM-generated shell scripts fail in exactly the ways ShellCheck catches (unquoted expansions, word splitting, cd without || exit). Existing Python packages such as shellcheck-py just download the 30 MB Haskell binary — useless in WASM, Lambda layers, or hermetic build sandboxes. pureshellcheck is ~7000 lines of stdlib-only Python.
• In-process speed. Calling pureshellcheck.check() takes ~1.3 ms for a typical script vs ~50 ms to spawn the shellcheck binary (38×), and is ~33× faster than the binary even on 1200-line scripts; one-line snippets check in ~40 µs (see Benchmarks).
• Verified against the real thing. Test cases are extracted from ShellCheck's own test suite and the output is differentially tested against the shellcheck binary on real-world scripts.

What it checks

71 SC codes are implemented, chosen by real-world frequency — the quoting and word-splitting family (SC2086, SC2046, SC2068, SC2206/2207...), variable lifecycle (SC2034 unused, SC2154 unassigned, SC2155), command pitfalls (SC2164 unchecked cd, SC2162 read without -r, useless cat/echo, ls | grep, find | xargs, printf argument counting, catastrophic rm -rf), structural mistakes (A && B || C, constant test expressions, $? anti-patterns), and more.

Conformance scoreboard

The repository vendors 1508 test cases extracted from ShellCheck's own test suite (tests/data/corpus.json), run by pytest on every commit:

The single implemented-check failure is documented in tests/data/expected_failures.txt (a test of ShellCheck's non-default check-unassigned-uppercase mode); every other non-passing corpus case is listed there with a reason. Reproduce with:

$ python tools/conformance.py                  # scoreboard
$ python tools/diff_shellcheck.py *.sh         # vs the real binary

Usage

CLI

$ pureshellcheck [-s bash] [-f tty|gcc|json|json1] [-e SC2086] \
                 [-S error|warning|info|style] script.sh [more.sh ...]

Exit status is 0 for a clean script, 1 if there are findings, 2 on file errors — same convention as shellcheck. # shellcheck disable=SC2086 and # shellcheck shell=dash directives are honored.

Library

import pureshellcheck

for f in pureshellcheck.check('echo $foo', shell='bash'):
    print(f.line, f.column, f.code, f.severity, f.message)
# 1 6 2086 info Double quote to prevent globbing and word splitting.

check() returns a list of findings with code, severity (error|warning|info|style), message, and 1-based line/column/end_line/end_column. pureshellcheck.parse() exposes the bash AST if you want to build your own analyses.

Benchmarks

All numbers: CPython 3.12, shellcheck 0.11.0, Apple Silicon. Two experiments, each repeated in 3 independent sessions; medians shown (session-to-session spread was < 4% everywhere). In both experiments the findings are verified identical before any timing.

vs the shellcheck binary (python tools/bench.py, median of 9 runs per session; both tools timed in the same session):

The embedded rows are what an agent or editor integration pays per call: no process spawn, no binary. A one-line snippet checks in ~40 µs (~25,000 checks/second); throughput on large scripts is ~57k lines/s. CLI time is dominated by CPython interpreter startup (~20 ms).

v0.2.x vs v0.1.0 (controlled before/after, python tools/bench_compare.py: baseline wheel from PyPI vs this tree in the same interpreter, 25–200 in-process repeats, outputs verified identical on every workload):

The speedups came from caching the AST child/parent structure and a document-order node table (one traversal instead of dozens), making variable states immutable tuples so branch snapshots are plain dict copies, a leaf-node fast path, a banded Levenshtein for SC2153 (fuzz-tested against the reference implementation on 20,000 random pairs), and memoizing repeated word/command resolution. Package import is 3.6 ms; remaining CLI latency is CPython interpreter startup.

Compatibility notes

• Targets bash (default), sh/dash/ash and ksh dialects are accepted via shebang, directive, or -s; sh-specific portability checks (the SC2039/SC3xxx family) are not implemented yet.
• The parser is deliberately lenient: it keeps checking past constructs the real shellcheck refuses to parse (e.g. [ $tar --version ]).
• Optional checks (SC2002, SC2248, SC2250) are off by default, matching shellcheck 0.11; enable with -o / include_optional=True.
• Wiki links work the same: see https://www.shellcheck.net/wiki/SC2086 for any reported code.

Development

$ pip install -e . pytest
$ pytest                                # corpus + unit tests, < 1 s
$ python tools/extract_corpus.py /path/to/shellcheck   # refresh corpus
$ python tools/update_expected_failures.py             # refresh scoreboard
$ python tools/bench.py                                # benchmarks

The package itself is MIT licensed and has zero runtime dependencies (CPython 3.9–3.14 and PyPy). The vendored test corpus in tests/data/ is extracted from the GPLv3-licensed ShellCheck project and is used only for development-time testing; it is not part of the distributed wheel.

See also

• purejq — pure Python jq, same philosophy: vendored official test suite, differential testing, no binaries.