ShellCheck – Shell script checker
Summary
ShellCheck is a static analysis tool for shell scripts that identifies syntax, semantic, and portability issues across Bash, Dash, Ksh, and Sh dialects.
Introduction #
ShellCheck is a static analysis tool that detects syntax errors, semantic mistakes, and common pitfalls in shell scripts. It supports multiple shell dialects, including Bourne shell (sh), Bourne Again shell (bash), Debian Almquist shell (dash), and Korn shell (ksh). ShellCheck helps you write robust, portable scripts that behave as intended across different environments.
Goals of ShellCheck #
The main goals of ShellCheck are:
- To identify and explain beginner-level syntax errors that typically result in unclear or cryptic shell error messages.
- To highlight intermediate-level semantic issues that may cause unexpected or counterintuitive shell behavior.
- To warn about subtle corner cases and pitfalls that might cause a working script to fail in the future or in different environments.
Usage #
You can use ShellCheck in several ways, depending on your workflow and environment.
On the web #
You can use ShellCheck directly in your browser at https://www.shellcheck.net/. Paste your shell script into the online editor to view warnings and suggestions instantly.
From the terminal #
Once installed, you can analyze a script by running:
shellcheck yourscript.sh
ShellCheck will output warnings and suggestions, including the line number, warning code, and explanation.
In your editor #
ShellCheck integrates with many code editors through plugins and extensions, such as:
- Visual Studio Code
- Vim
- Emacs
- Sublime Text
- Atom
- JetBrains IDEs
These integrations highlight issues in real time as you write your script.
In your build or test suites #
ShellCheck can be part of continuous integration (CI) workflows or automated tests to ensure shell script quality. For example, add it to a Makefile or GitHub Actions workflow to fail builds when warnings are detected.
Installing ShellCheck #
On systems with Cabal #
cabal update
cabal install ShellCheck
The binary will be installed in ~/.cabal/bin.
On systems with Stack #
stack update
stack install ShellCheck
The binary will be installed in ~/.local/bin.
On Debian-based distributions #
sudo apt install shellcheck
On Arch Linux-based distributions #
pacman -S shellcheck
Alternatively, you can install the dependency-free shellcheck-bin package from the Arch User Repository (AUR).
On Gentoo-based distributions #
emerge --ask shellcheck
On EPEL-based distributions #
sudo yum -y install epel-release
sudo yum install ShellCheck
On Fedora-based distributions #
dnf install ShellCheck
On FreeBSD #
pkg install hs-ShellCheck
On macOS with Homebrew #
brew install shellcheck
On macOS with MacPorts #
sudo port install shellcheck
On OpenBSD #
pkg_add shellcheck
On openSUSE #
zypper in ShellCheck
Alternatively, use OneClickInstall.
On Solus #
eopkg install shellcheck
On Windows using Chocolatey #
C:\> choco install shellcheck
On Windows using Winget #
C:\> winget install --id koalaman.shellcheck
On Windows using Scoop #
C:\> scoop install shellcheck
From Conda-Forge #
conda install -c conda-forge shellcheck
From Snap Store #
snap install --channel=edge shellcheck
From Docker Hub #
Run ShellCheck in a container:
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable myscript
To use a specific version:
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:v0.4.7 myscript
Or use the :latest tag for daily builds.
You can also use koalaman/shellcheck-alpine for an Alpine Linux-based image with ShellCheck preinstalled.
Using the Nix package manager #
nix-env -iA nixpkgs.shellcheck
Using the Flox package manager #
flox install shellcheck
Synopsis #
shellcheck [OPTIONS...] FILES...
Options #
| Short | Long | Description |
|---|---|---|
-a | --check-sourced | Include warnings from sourced files |
-C[WHEN] | --color[=WHEN] | Use color (auto, always, never) |
-i CODE1,CODE2.. | --include=CODE1,CODE2.. | Include only the specified types of warnings |
-e CODE1,CODE2.. | --exclude=CODE1,CODE2.. | Exclude specific warning types |
-f FORMAT | --format=FORMAT | Set output format (checkstyle, diff, gcc, json, json1, quiet, tty) |
--list-optional | List checks disabled by default | |
--norc | Do not read .shellcheckrc configuration files | |
-o check1,check2.. | --enable=check1,check2.. | Enable specific optional checks or all checks |
-P SOURCEPATHS | --source-path=SOURCEPATHS | Define path when looking for sourced files (SCRIPTDIR for script’s directory) |
-s SHELLNAME | --shell=SHELLNAME | Specify shell dialect (sh, bash, dash, ksh) |
-S SEVERITY | --severity=SEVERITY | Minimum severity to report (error, warning, info, style) |
-V | --version | Display version information |
-W NUM | --wiki-link-count=NUM | Number of wiki links to show in output |
-x | --external-sources | Allow analysis of sourced files outside provided FILES |
--help | Show help message and exit |
FAQ's #
Most common questions and brief, easy-to-understand answers on the topic:
What is ShellCheck?
ShellCheck is a static analysis tool that scans shell scripts for syntax errors, semantic issues, and common pitfalls across multiple shell dialects.
Which shells are supported by ShellCheck?
ShellCheck supports sh, bash, dash, and ksh dialects.
Can I use ShellCheck in my text editor?
Yes. ShellCheck integrates with many editors, including Visual Studio Code, Vim, Emacs, Sublime Text, and Atom, through available plugins.
Does ShellCheck require internet access to work?
No. Once installed locally, ShellCheck runs entirely offline and performs static analysis directly on your scripts.
Is ShellCheck available for Windows?
Yes. You can install ShellCheck on Windows using Chocolatey, Scoop, or Winget.
Further readings #
Sources and recommended, further resources on the topic:
Author
Jonas Jared Jacek (J15k)
Jonas works as project manager, web designer, and web developer since 2001. On top of that, he is a Linux system administrator with a broad interest in things related to programming, architecture, and design. See: https://www.j15k.com/License
ShellCheck – Shell script checker by Jonas Jared Jacek is licensed under CC BY-SA 4.0.
This license requires that reusers give credit to the creator. It allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, for noncommercial purposes only. To give credit, provide a link back to the original source, the author, and the license e.g. like this:
<p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://www.ditig.com/shellcheck-shell-script-checker">ShellCheck – Shell script checker</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://www.j15k.com/">Jonas Jared Jacek</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="license noopener noreferrer">CC BY-SA 4.0</a>.</p>For more information see the Ditig legal page.
