{"id":2281,"library":"shellcheck-py","title":"shellcheck-py","description":"shellcheck-py is a Python wrapper designed to provide a pip-installable `shellcheck` binary. It internally downloads the pre-built `shellcheck` static analysis tool for shell scripts, making it available in your environment without needing system-level package managers. The current version is 0.11.0.1. The library's release cadence appears to be driven by updates to the underlying `shellcheck` tool and Python compatibility.","status":"active","version":"0.11.0.1","language":"en","source_language":"en","source_url":"https://github.com/ryanrhee/shellcheck-py","tags":["shell","linter","static analysis","shellcheck","pre-commit"],"install":[{"cmd":"pip install shellcheck-py","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"The 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.","package":"shellcheck (binary)","optional":false}],"imports":[{"note":"The primary interaction with `shellcheck-py` is not through direct Python imports for linting functions, but by invoking the `shellcheck` binary that the package installs onto your PATH. There is no public Python API for the linter functionality itself.","symbol":"shellcheck binary","correct":"import subprocess\nsubprocess.run([\"shellcheck\", \"myscript.sh\"])"}],"quickstart":{"code":"import subprocess\nimport os\n\n# Create a dummy shell script for demonstration\nscript_content = '''#!/bin/bash\n\n# SC2034: foo appears unused. Verify use (or export if used externally).\nfoo=\"bar\"\n\necho $foo\n'''\n\nwith open(\"test_script.sh\", \"w\") as f:\n    f.write(script_content)\n\nos.chmod(\"test_script.sh\", 0o755) # Make it executable\n\nprint(\"Running shellcheck on test_script.sh:\")\ntry:\n    # Run shellcheck, capturing output. -f json for machine-readable output\n    result = subprocess.run(\n        ['shellcheck', '-f', 'json', 'test_script.sh'],\n        capture_output=True,\n        text=True,\n        check=False # Don't raise an exception for non-zero exit codes (warnings/errors)\n    )\n    print(\"Standard Output:\")\n    print(result.stdout)\n    if result.stderr:\n        print(\"Standard Error:\")\n        print(result.stderr)\n    print(f\"Exit Code: {result.returncode}\")\nexcept FileNotFoundError:\n    print(\"Error: 'shellcheck' command not found. Ensure shellcheck-py is installed correctly.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy script\n    if os.path.exists(\"test_script.sh\"):\n        os.remove(\"test_script.sh\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Use `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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade 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.","message":"Older 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).","severity":"breaking","affected_versions":"<=0.10.0.1 (specifically with Python < 3.12 and pip >= 23.1)"},{"fix":"For 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.","message":"While `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}