ShellCheck is a code verifier that spots bugs, incompatibilities, and other problems in shell scripts. It’s valuable because few similar tools exist, and shell programming can be particularly flaky, with portability concerns and different syntax changes introduced over time.

I unleashed ShellCheck on my own scripts—and a few third-party ones—and, unsurprisingly, it caught quite a few problems. So I’d recommend you do the same!

What is ShellCheck?

A shell script static analysis tool (and website)

ShellCheck bills itself as a “shell script static analysis tool,” meaning that you run it in a terminal, and it tells you how good your shell scripts are. Specifically, it carries out its job just by looking at the source code of your scripts, not by actually running them.

The program will warn you about various problems in your code, including:

• Syntax errors and problems
• Common semantic errors
• Incompatibilities
• Style issues that may not cause problems, but can lead to less readable code

For example, here’s a tiny shell script, repeat.sh, that prints its first argument:

#!/bin/bash
echo $1

You might think that there’s little to go wrong with such a simple script, but ShellCheck will correct that misconception:

How do you use it?

Command-line and web versions are available

For a start, ShellCheck has an excellent web app which mirrors the latest version of the code and lets you try it out without installing a thing. I wouldn’t recommend using it long-term because it’s much less convenient, but it’s a great way to test the software and see what it does.

If you decide to try ShellCheck for real, start with the installation instructions for your platform. On Debian/Ubuntu, it’s sudo apt install shellcheck; on Fedora, use dnf install ShellCheck. If you have Homebrew, run brew install shellcheck.

Once it’s installed, you can run the tool with the command shellcheck. Without any arguments, you’ll get usage information:

Now try running shellcheck on a script file to see some useful results, e.g.:

shellcheck script.sh

If your script has any problems in it, you should notice that ShellCheck provides several bits of useful information. For a start, it will describe each problem it encounters, with the file name, line number, and specific position in the line, e.g.:

Alongside the specific error message, ShellCheck offers a suggested alternative, plus a set of reference links at the end to each unique issue. These pages give much more detail, including why people might make a particular mistake, and whether there are exceptions to the rule.

ShellCheck has a few options that you can use to tweak how it operates. The --format=json option will give you output in a more structured format, should you want to process it further. With --severity=error, you’ll only get errors reported; style, info, and warning types will be ignored. And the --include= and --exclude= options can be followed by a comma-separated list of specific codes to refine the scope. You can omit the leading “SC” if you want.

What kinds of problems can ShellCheck uncover?

The best way to find out is to try it

Many things can go wrong with shell scripts. Shell script is almost always interpreted, and the language is usually forgiving, with loose (or nonexistent) typing. There are many syntax differences between versions, and alternative syntaxes are maintained to provide backward compatibility. Moreover, there are different shells—like Bash and Zsh—that are more or less interchangeable, yet still retain some differences.

ShellCheck aims to uncover all these problems, so it’s pretty comprehensive. Here’s an example from one of my own shell scripts:

This highlights a very common problem: the use of legacy syntax. While the backtick syntax (“) works for command substitution, it’s not ideal; for one thing, it doesn’t allow commands to be nested. The more modern $(...) variant is POSIX-compliant, so there’s no good reason to avoid it.

ShellCheck also caught my sloppy use of $0 without quotes. As the info message explains, this helps to prevent expansions that I’m probably not expecting. These two problems are both stylistic, so they’re not too much of a concern, but the next finding is more serious:

This is an actual warning—note the slight color difference—because it reveals a fundamental misunderstanding: the order of 2>&1 and other redirections is important. My bad version will still show errors on the command line, even though I’m redirecting stdout to /dev/null, because of the order.

This is the exact kind of problem that is difficult to spot: it shouldn’t come up during normal program execution, and it could even be what I intended, it’s just unlikely. Thankfully, ShellCheck is clever enough to warn me about this technically correct but weird code!

To make myself feel a bit better, I checked some shell scripts that proper, public, open-source projects use. Fortunately for me, I’m not the only one who produces sloppy shell scripts! The report for the excellent bashblog tool included many problems. It’s a much bigger script, of course, but it helps demonstrate the issues that ShellCheck can catch.

The quality of your shell scripts matters too

Because shell scripts are often private or written to perform a throwaway task, it’s easy to get sloppy and miss important problems, even bugs. But we should treat shell scripts with just as much care as other types of programs.

Shell scripts can mutate over time, serving purposes they weren’t originally intended for. You never know where your code will end up, or who may one day use it, so make sure it’s as bulletproof as you can, while that’s easy to do.