Install & Compatibility
Where this runs
tested against v0.11.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
shellcheck
✓ import shellcheck_py
✗ from shellcheck_py import shellcheck
This quickstart demonstrates how to programmatically use the `shellcheck` binary installed by `shellcheck-py` via Python's `subprocess` module. It creates a simple shell script with a known `shellcheck` warning (SC2034) and then invokes `shellcheck` to analyze it, printing the JSON output and exit code.
import subprocess
import os
# Create a dummy shell script for demonstration
script_content = '''#!/bin/bash
# SC2034: foo appears unused. Verify use (or export if used externally).
foo="bar"
echo $foo
'''
with open("test_script.sh", "w") as f:
f.write(script_content)
os.chmod("test_script.sh", 0o755) # Make it executable
print("Running shellcheck on test_script.sh:")
try:
# Run shellcheck, capturing output. -f json for machine-readable output
result = subprocess.run(
['shellcheck', '-f', 'json', 'test_script.sh'],
capture_output=True,
text=True,
check=False # Don't raise an exception for non-zero exit codes (warnings/errors)
)
print("Standard Output:")
print(result.stdout)
if result.stderr:
print("Standard Error:")
print(result.stderr)
print(f"Exit Code: {result.returncode}")
except FileNotFoundError:
print("Error: 'shellcheck' command not found. Ensure shellcheck-py is installed correctly.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the dummy script
if os.path.exists("test_script.sh"):
os.remove("test_script.sh")
shellcheck --version
Debug
Known issues
gotchaThe `shellcheck-py` package installs the `shellcheck` binary to your environment's PATH, rather than providing Python functions for direct linting. Interaction with the linter is typically done by executing the `shellcheck` command via `subprocess` or as a pre-commit hook.fixUse `subprocess.run(['shellcheck', ...])` to invoke the installed binary or integrate it as a pre-commit hook. Consult `shellcheck`'s official documentation for command-line arguments and output formats.
affects: All versions
breakingOlder Python versions (e.g., 3.10/3.11) may encounter installation failures due to `shellcheck-py` using the deprecated `setup.py install` method, especially if the `wheel` package is not installed. `pip` versions 23.1 and above are enforcing stricter build standards (PEP 517).fixUpgrade to Python 3.12 or newer. Ensure your `pip` is up-to-date (`pip install --upgrade pip`) and the `wheel` package is installed (`pip install wheel`). If issues persist, consider installing `shellcheck` directly via your system's package manager if `shellcheck-py` isn't strictly required for its bundling capabilities.
affects: <=0.10.0.1 (specifically with Python < 3.12 and pip >= 23.1)
gotchaWhile `shellcheck-py` aims to make `shellcheck` easily installable, it still relies on platform-specific pre-built binaries. Issues related to binary compatibility with highly specific or unusual system architectures might occur, though less common for mainstream OSes.fixFor highly custom environments or if encountering binary execution issues, verify the `shellcheck` binary itself is compatible with your system architecture. In such rare cases, installing `shellcheck` via its source or alternative distribution methods might be necessary. Refer to the official `shellcheck` project's installation instructions.
affects: All versions
Upgrade
Version history
0.11.0.1latest on PyPI · released Aug 9, 2025
Audit
Dependencies
shellcheck (binary)requiredThe Python package wraps and installs the actual `shellcheck` binary, which is essential for its functionality. It is downloaded automatically by `shellcheck-py` for your platform.