← Full reference

shellcheck

Static analyzer for shell scripts — finds mistakes with quoting, conditions and portability

shellcheck reads a script without running it and points out typical mistakes: unquoted variables, cd without a check, looping over ls output, bash constructs in #!/bin/sh. Every warning has an SCxxxx code — shellcheck.net/wiki has a detailed explanation for it with an example fix.

Syntax

shellcheck [options] script…

The dialect is taken from the shebang (#!/bin/bash, #!/bin/sh) or from the -s option. Exit code: 0 — no findings, 1 — there are findings, 2 — a file couldn't be read, 3 and 4 — an error in the options.

Options

OptionWhat it does
-s bash / -s sh / -s dash / -s kshdialect, if the file has no shebang
-S error / warning / info / styleshow only findings of this severity and above
-e SC2086,SC2034exclude the given codes
-i SC2086show only the given codes
-o all / -o nameenable optional checks (off by default)
--list-optionallist optional checks with examples
-xfollow files included via source / .
-P pathwhere to look for included files (SCRIPTDIR — the script's directory)
-aalso show findings for included files
-f ttythe default format: code line, arrow, explanation, "Did you mean"
-f gccone line per finding: file:line:column: severity: text [SCxxxx]
-f difffixes as a patch (shellcheck -f diff s.sh | patch -p1)
-f json1 / -f checkstylemachine-readable output for CI
-f quietprint nothing, only the exit code
--color=neverno colors (with -C the value is attached: -Cnever)
-W 0don't print wiki links at the end
--norcdon't read .shellcheckrc
- instead of a fileread the script from stdin

Severities

SeverityWhat it usually means
erroralmost certainly a mistake: syntax, a loop over $(ls), [[ in sh
warninga likely bug: cd without a check, a variable unset or unused
infoworth fixing: quoting, read without -r
stylestyle: $(…) instead of backticks, [[ ]] instead of [ ]

Directives in a script

CommentWhat it does
# shellcheck disable=SC2086disable a code for the next command (or a { … } block, function, loop)
the same right after the shebang, before the first commanddisable for the whole file
# shellcheck disable=SC2086,SC2154several codes, comma-separated
# shellcheck source=lib.shwhich file source "$dir/lib.sh" actually includes
# shellcheck source=/dev/nulldon't try to read the included file
# shellcheck shell=bashset the dialect inside a file without a shebang

A .shellcheckrc file in the project directory or in your home directory sets the same directives for all scripts: disable=SC2086, enable=all, shell=bash.

Common codes

CodeGist
SC2086an unquoted variable will be split into words and expanded as a glob
SC2164cd without || exit: if the directory doesn't exist, the commands run in the wrong place
SC2045for f in $(ls …) breaks on spaces — use a glob
SC2154a variable is used but never assigned
SC2034a variable is assigned but never used
SC2162read without -r mangles backslashes
SC2155local x=$(cmd) hides cmd's exit code
SC2148no shebang — the dialect is unknown
SC1091an included file wasn't read (needs -x)
SC3010 and other SC3xxxa bash construct in POSIX sh

Examples

# check a script
shellcheck deploy.sh

# compact output — handy for grep and editors
shellcheck -f gcc deploy.sh

# only errors and warnings, no info and style
shellcheck -S warning deploy.sh

# a script without a shebang
shellcheck -s bash script

# check all .sh files in a project
find . -name '*.sh' -exec shellcheck {} +

# view the suggested fixes as a patch
shellcheck -f diff deploy.sh

# in CI: fail if there is at least one finding
shellcheck -f quiet *.sh || exit 1

# check a snippet from stdin
echo 'echo $1' | shellcheck -s bash -

Pitfalls

  • shellcheck doesn't run the script. It doesn't know whether files and commands exist and won't find logic errors. Clean output doesn't mean "the script works".
  • Without a shebang almost all dialect checks are off, and the first finding will be SC2148. Add #!/bin/bash or pass -s.
  • #!/bin/sh is not bash. [[ ]], arrays, &> give SC3xxx. That's correct: on Ubuntu sh is dash, and such a script will break.
  • A directive applies to the next command, not to the line. A comment at the end of a line (echo $x # shellcheck disable=…) is a parse error SC1126. And a directive right after the shebang, before the first command, disables the check for the whole file.
  • disable silences the symptom. Before disabling SC2086, make sure word splitting is really what you want.
  • Included files aren't read by default: variables from them look unassigned (SC2154). Add -x.

See also

variables · conditions-loops · exit-codes · find