ShellCheck: 39,456 GitHub Stars — Complete Setup Guide for Shell Script Analysis in 2026

{{< resource-info >}}

ShellCheck is the de facto standard for catching bugs in shell scripts before they hit production. With 39,456+ GitHub stars and a maintained open-source community, it is the most widely adopted static analysis tool for bash, sh, dash, and ksh scripts. This guide walks through installing ShellCheck, integrating it with editors and CI/CD pipelines, and hardening it for production use.

Introduction #

Shell scripts power deployment pipelines, system automation, and infrastructure management. A single unquoted variable or an unchecked return code can corrupt data, expose credentials, or take down a production server. The 2014 Heartbleed aftermath and countless CI/CD outages trace back to shell script bugs that static analysis would have caught.

ShellCheck, created by Vidar Holen in 2012, addresses this gap. It parses shell scripts without executing them, identifying syntax errors, semantic pitfalls, portability issues, and security vulnerabilities. With over 280 built-in checks (each assigned a unique SC code), it catches everything from beginner mistakes to subtle corner cases that trip up experienced developers.

This guide covers a complete ShellCheck tutorial and shellcheck setup guide: installation on multiple platforms, editor integration, Docker usage, GitHub Actions setup, and production hardening. Whether you are doing bash linting for a single deployment script or enforcing quality gates across a monorepo using shellcheck docker images, the configurations below are ready to copy, adapt, and deploy.

What Is ShellCheck? #

ShellCheck is a static analysis tool (“linter”) for shell scripts. It reads bash/sh/dash/ksh source code, builds an abstract syntax tree (AST), and applies semantic rules to detect bugs, anti-patterns, and style violations — all without executing the script.

The project is written in Haskell (96.4% of the codebase), distributed under the GPL-3.0 license, and maintained by Vidar Holen with 166+ contributors. Stable version v0.11.0 was released August 4, 2025.

Key Capabilities #

• Syntax validation: Catches malformed constructs before runtime
• Semantic analysis: Detects unquoted variables, unreachable code, and masked exit codes
• Portability checking: Flags bashisms in /bin/sh scripts intended for POSIX compliance
• Security auditing: Identifies command injection vectors and unsafe eval patterns
• Style enforcement: Suggests modern constructs over deprecated syntax

How ShellCheck Works #

ShellCheck operates as a multi-stage analysis pipeline. Understanding this architecture helps when tuning performance or interpreting results.

Architecture Overview #

Source Script → Lexer → Parser (AST) → Analyzer → Reporter
                     ↓           ↓            ↓
                 Tokens    Syntax Tree    SC-Warnings

1. Lexer: Tokenizes the shell script into identifiers, keywords, operators, and literals
2. Parser: Builds an AST from the token stream, handling shell-specific grammar quirks
3. Analyzer: Traverses the AST and applies ~280+ rules, each mapped to an SC error code
4. Reporter: Formats findings as terminal output, JSON, CheckStyle XML, GCC-compatible warnings, or SARIF

Severity Levels #

Every ShellCheck finding carries one of four severity levels:

Core Check Categories #

• SC1xxx: Syntax and parsing issues (e.g., SC1007 — space after =)
• SC2xxx: Semantic and portability warnings (e.g., SC2086 — unquoted variable)
• SC3xxx: Bash/dash/ksh-specific compatibility notes
• SC4xxx: Optional checks and experimental rules

Installation and Setup #

ShellCheck is available on every major platform. Installation takes under two minutes.

Linux (APT / Debian / Ubuntu) #

# Update package index
sudo apt update

# Install ShellCheck
sudo apt install -y shellcheck

# Verify version
shellcheck --version
# ShellCheck - shell script analysis tool
# version: 0.11.0
# license: GNU General Public License, version 3
# website: https://www.shellcheck.net

Linux (DNF / Fedora / RHEL) #

# Install via DNF
sudo dnf install -y shellcheck

# Verify
shellcheck --version

macOS (Homebrew) #

# Install via Homebrew
brew install shellcheck

# Verify
shellcheck --version

Windows (via Chocolatey) #

# Install via Chocolatey (administrator prompt)
choco install shellcheck

# Verify
shellcheck --version

Docker (Platform-Independent) #

# Run ShellCheck via Docker without local installation
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable \
  /mnt/deploy.sh

# Check all scripts in the current directory
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable \
  /mnt/*.sh

# Pin to a specific version for reproducible CI builds
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:v0.11.0 \
  /mnt/deploy.sh

Building from Source (Haskell Stack) #

# Clone the repository
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck

# Build with Stack
stack install

# Or build with Cabal
cabal update
cabal install

Pre-commit Hook #

# Add to your .pre-commit-config.yaml
repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.11.0
    hooks:
      - id: shellcheck
        args: ["--severity=warning"]

Editor Integration #

ShellCheck shines when feedback appears in real-time as you type. Every major editor has a ShellCheck plugin.

VS Code #

Install the ShellCheck extension by Timon Wong (marketplace ID: timonwong.shellcheck).

// settings.json
{
  "shellcheck.executablePath": "shellcheck",
  "shellcheck.exclude": ["SC1090", "SC1091"],
  "shellcheck.severity": "warning",
  "shellcheck.run": "onType"
}

Vim / Neovim #

Using ALE (Asynchronous Lint Engine):

" .vimrc or init.vim
let g:ale_linters = {
\   'sh': ['shellcheck'],
\}

" Run on save and while typing
let g:ale_lint_on_save = 1
let g:ale_lint_on_text_changed = 'always'

Using native LSP in Neovim with bash-language-server:

-- init.lua (nvim-lspconfig)
require('lspconfig').bashls.setup {
  settings = {
    bashIde = {
      shellcheckPath = "shellcheck"
    }
  }
}

Emacs #

;; init.el with Flycheck
(add-hook 'sh-mode-hook #'flycheck-mode)
(setq flycheck-shellcheck-severity "warning")

Sublime Text #

Install via Package Control: SublimeLinter-shellcheck.

// SublimeLinter.sublime-settings
{
  "linters": {
    "shellcheck": {
      "executable": "shellcheck",
      "args": ["--severity=warning"]
    }
  }
}

CI/CD Integration #

Running ShellCheck in CI prevents buggy scripts from merging. Below are ready-to-use configurations for GitHub Actions, GitLab CI, and Jenkins.

GitHub Actions #

# .github/workflows/shellcheck.yml
name: ShellCheck

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run ShellCheck
        uses: ludeeus/action-shellcheck@master
        env:
          SEVERITY: warning
        with:
          ignore_paths: >-
            ./vendor
            ./third_party

Alternative: manual setup with pinned version:

# .github/workflows/shellcheck-manual.yml
name: ShellCheck Manual

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ShellCheck
        run: |
          wget -qO- "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz" | tar -xJf -
          sudo cp "shellcheck-v0.11.0/shellcheck" /usr/local/bin/

      - name: Lint all shell scripts
        run: |
          find . -name "*.sh" -type f -print0 | \
            xargs -0 shellcheck --severity=warning --format=tty

GitLab CI #

# .gitlab-ci.yml
stages:
  - lint

shellcheck:
  stage: lint
  image: koalaman/shellcheck-alpine:stable
  script:
    - find . -name "*.sh" -type f -exec shellcheck --severity=warning {} +
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Jenkins #

// Jenkinsfile
pipeline {
    agent any

    stages {
        stage('ShellCheck') {
            steps {
                sh '''
                    #!/bin/bash
                    set -euo pipefail

                    if ! command -v shellcheck &> /dev/null; then
                        echo "Installing ShellCheck..."
                        apt-get update && apt-get install -y shellcheck
                    fi

                    find . -name "*.sh" -type f -print0 | \
                        xargs -0 shellcheck --severity=warning
                '''
            }
        }
    }

    post {
        failure {
            echo "ShellCheck found issues. Review the build log."
        }
    }
}

CircleCI #

# .circleci/config.yml
version: 2.1
orbs:
  shellcheck: circleci/shellcheck@3.2.0

workflows:
  lint:
    jobs:
      - shellcheck/check:
          severity: "warning"
          exclude: "SC1090,SC1091"

Configuration and Rule Management #

ShellCheck provides multiple mechanisms for controlling which checks run and how they are reported.

Inline Directives #

#!/bin/bash
# shellcheck disable=SC2086
echo $UNQUOTED_VAR  # This line disables SC2086

# shellcheck disable=SC2034
UNUSED_VAR="this is assigned but not used"

# Re-enable after a block
# shellcheck enable=SC2086
echo "$PROPERLY_QUOTED"

Configuration File (.shellcheckrc) #

# .shellcheckrc — project-level configuration
# Place in repo root or $HOME/.shellcheckrc

# Set shell dialect for scripts without a shebang
shell=bash

# Exclude specific checks globally
disable=SC1090,SC1091,SC2155

# Set minimum severity (error, warning, info, style)
severity=warning

# Enable optional checks
enable=require-variable-braces,check-set-e-suppressed

# Specify external sources (for sourced files)
external-sources=true

Severity Filtering #

# Only report errors and warnings (no info/style)
shellcheck --severity=warning script.sh

# Only report errors
shellcheck --severity=error script.sh

Output Formats #

# Human-readable terminal output (default)
shellcheck --format=tty script.sh

# JSON output for programmatic processing
shellcheck --format=json script.sh > shellcheck-report.json

# CheckStyle XML (Jenkins, GitLab compatible)
shellcheck --format=checkstyle script.sh > shellcheck.xml

# GCC-compatible warnings (for generic editor integration)
shellcheck --format=gcc script.sh

# SARIF output for GitHub Security tab integration
shellcheck --format=sarif script.sh > shellcheck.sarif

Benchmarks and Real-World Use Cases #

ShellCheck adoption spans individual developers to enterprise CI/CD pipelines. Below are benchmarks and usage metrics.

Performance Benchmarks #

Tested on a 2024-standard CI runner (Ubuntu 24.04, 2 vCPU, 4 GB RAM):

Real-World Adoption #

• GitHub Actions: Official ludeeus/action-shellcheck runs 500K+ monthly executions
• Homebrew: Linted all 5,000+ formula shell scripts with ShellCheck
• Google’s Shell Style Guide: Recommends ShellCheck for all shell scripts
• NixOS: Uses ShellCheck in the official package build pipeline
• Debian / Ubuntu: Packaged and maintained in the official repositories

Bug Categories Detected (Sample Analysis of 1,000 Open-Source Scripts) #

Advanced Usage and Production Hardening #

For teams running ShellCheck at scale, these patterns improve reliability and maintainability.

Multi-Script Batch Analysis #

#!/bin/bash
set -euo pipefail

SEVERITY="warning"
SCRIPT_DIRS=("scripts/" "bin/" "deploy/")
EXCLUDES=()

# Build exclude list
for code in SC1090 SC1091 SC2155; do
    EXCLUDES+=("-e" "$code")
done

# Find and lint all shell scripts
find "${SCRIPT_DIRS[@]}" -name "*.sh" -type f -print0 | \
    xargs -0 shellcheck --severity="$SEVERITY" "${EXCLUDES[@]}"

echo "All scripts passed ShellCheck at severity: $SEVERITY"

SARIF Upload for GitHub Security Dashboard #

# .github/workflows/security-scan.yml
name: Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Run ShellCheck SARIF
        run: |
          find . -name "*.sh" -type f -print0 | \
            xargs -0 shellcheck --format=sarif > shellcheck.sarif || true

      - name: Upload to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: shellcheck.sarif

Dockerfile Linting Stage #

# Dockerfile
FROM koalaman/shellcheck:stable AS lint
WORKDIR /scripts
COPY . .
RUN find . -name "*.sh" -exec shellcheck --severity=warning {} +

FROM alpine:3.20 AS runtime
COPY --from=lint /scripts/deploy.sh /usr/local/bin/
ENTRYPOINT ["/usr/local/bin/deploy.sh"]

Monitoring ShellCheck in CI #

Track ShellCheck failures as a team metric:

#!/bin/bash
# ci-metrics.sh — track shellcheck warning count over time

WARNINGS=$(find . -name "*.sh" -exec shellcheck --severity=warning --format=json {} + | \
    jq '. | length')

echo "shellcheck_warnings $WARNINGS" >> metrics.txt

Comparison with Alternatives #

When to Choose Each Tool #

• ShellCheck: General-purpose shell script quality and security auditing. The default choice.
• bash -n: Quick syntax validation for bash scripts when nothing else is available.
• shfmt: Code formatting and style normalization. Complements ShellCheck (not a replacement).
• checkbashisms: Debian-specific portability checking. Use when packaging for Debian/Ubuntu.

Limitations and Honest Assessment #

ShellCheck is not a silver bullet. Understanding its boundaries prevents false confidence.

What ShellCheck Does NOT Catch #

• Runtime logic errors: It cannot determine if your curl command targets the correct endpoint
• Business logic bugs: It validates syntax, not whether your backup script backs up the right directory
• Performance issues: Infinite loops with valid syntax pass cleanly
• Turing-complete analysis: Some dynamic behavior (e.g., eval "$DYNAMIC_CMD") is inherently unanalyzable

Platform and Environment Gaps #

• ShellCheck assumes standard Unix utilities. Scripts targeting embedded systems or busybox environments may trigger false positives
• Some SC rules are opinionated. Teams should review and customize .shellcheckrc rather than blindly applying all suggestions
• Windows-native scripts (PowerShell, CMD) are not supported

Build and Dependency Considerations #

• The Haskell runtime adds ~30 MB to Docker images when built from source
• Pre-built binaries (the recommended approach) have no runtime dependencies
• CI pipelines should pin to a specific version to avoid build breaks from new checks in releases

Frequently Asked Questions #

What shells does ShellCheck support? #

ShellCheck supports bash, dash, sh, ksh, and busybox sh. It does not support PowerShell, zsh (partial), or fish. Specify the target shell with --shell bash|sh|dash|ksh or via the shebang line in your script.

How do I suppress a specific ShellCheck warning? #

Use inline directives: # shellcheck disable=SC2086 on the line before the warning. For project-wide suppression, add disable=SC2086 to your .shellcheckrc file. Each check has a wiki page at https://www.shellcheck.net/wiki/SC2086 explaining the rationale.

Can ShellCheck automatically fix my scripts? #

The web interface at shellcheck.net offers auto-fix suggestions for many common issues. The CLI tool shows suggested fixes in its output but does not modify files in-place. Some third-party tools wrap ShellCheck to apply fixes automatically.

How do I integrate ShellCheck with pre-commit hooks? #

Add the official pre-commit hook from https://github.com/koalaman/shellcheck-precommit to your .pre-commit-config.yaml. Set args: ["--severity=warning"] to block commits with warnings, or args: ["--severity=error"] to only block errors.

Is ShellCheck suitable for security auditing? #

ShellCheck identifies common security patterns like command injection (SC2096), unsafe eval usage, and unquoted variables that could expand maliciously. However, it is not a replacement for dedicated security scanners. Combine it with tools like Semgrep or GitHub CodeQL for comprehensive security coverage.

Why does ShellCheck flag code that works fine? #

Many ShellCheck warnings address “works now, breaks later” scenarios. An unquoted variable may work for filenames without spaces but fail on input with spaces or glob characters. The warnings prevent latent bugs from surfacing in production.

How do I run ShellCheck in a Docker container? #

Use the official image: docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable /mnt/script.sh. Pin to v0.11.0 or another specific version for reproducible CI builds. The image is based on Alpine Linux and weighs approximately 15 MB.

Conclusion #

ShellCheck is the most mature and widely adopted static analysis tool for shell scripts. With 39,456+ GitHub stars, comprehensive CI/CD integrations, and support for every major editor, it belongs in every developer toolchain. Start with the Docker one-liner for immediate feedback, add the .shellcheckrc project config for team consistency, and wire it into GitHub Actions to catch bugs before they merge.

Action items for your team:

1. Run shellcheck on your top 5 most critical deployment scripts today
2. Add the VS Code extension or Vim ALE integration for real-time feedback
3. Create a .shellcheckrc in your repository root with project-specific rules
4. Set up the GitHub Actions workflow to block merges on warnings

Join the dibi8 Telegram group for discussions on developer tools, CI/CD best practices, and DevOps automation.

Recommended Hosting & Infrastructure #

Before you deploy any of the tools above into production, you’ll need solid infrastructure. Two options dibi8 actually uses and recommends:

• DigitalOcean — $200 free credit for 60 days across 14+ global regions. The default option for indie devs running open-source AI tools.
• HTStack — Hong Kong VPS with low-latency access from mainland China. This is the same IDC that hosts dibi8.com — battle-tested in production.

Affiliate links — they don’t cost you extra and they help keep dibi8.com running.

Sources and Further Reading #

• ShellCheck Official Website
• ShellCheck GitHub Repository
• ShellCheck Wiki — All Check Codes
• ShellCheck v0.11.0 Release Notes
• ShellCheck Pre-commit Hook
• ludeeus/action-shellcheck — GitHub Action
• Google Shell Style Guide
• shfmt — Shell Formatter
• checkbashisms — Debian Devscripts
• POSIX.1-2017 Shell Command Language