How to Check and Debug Bash Scripts in Linux Terminal Using ShellCheck

Writing Bash and POSIX shell scripts is one of the most effective ways to automate routine system administration, server backups, software deployments, and file management tasks in Linux. However, shell scripting is notoriously unforgiving. Subtle syntax oversights\u2014such as missing quotes around variables containing spaces, using wrong comparison operators, or failing to handle edge cases\u2014can lead to catastrophic failures, including unintended file overwrites or silent script crashes.

Traditional debugging methods, such as adding temporary echo statements or running scripts with bash -x, only show what happened during execution after mistakes have already triggered. To identify bugs before running your code, the Linux ecosystem relies on ShellCheck: an open-source static analysis tool specifically built to parse shell scripts, highlight potential security hazards, and offer actionable syntax corrections. This guide explains how to install ShellCheck and use it to debug your shell scripts.

Installing ShellCheck on Linux

ShellCheck is widely packaged across all major Linux distributions and can be installed through standard package repositories:

• Ubuntu, Debian, and Linux Mint:

  sudo apt update && sudo apt install shellcheck

• Fedora, RHEL, and CentOS Stream:

  sudo dnf install ShellCheck

• Arch Linux and Manjaro:

  sudo pacman -S shellcheck

• openSUSE:

  sudo zypper install ShellCheck

Verify that the tool is installed and accessible by running shellcheck --version in your terminal.

Running ShellCheck on a Shell Script

Using ShellCheck is as simple as passing your script’s file path as an argument in your terminal:

shellcheck backup_script.sh

If your script contains syntax errors, logical oversights, or unquoted variables, ShellCheck outputs an informative report displaying:

• The Line and Column Number: Points precisely to where the problem was detected.
• The Problematic Code: Visual arrows (^--) highlighting the exact syntax error.
• An Issue Classification: Categorised as an error, warning, info, or style recommendation.
• A Unique Wiki Code: Codes such as SC2086 or SC2006 that correspond directly to detailed online explanations and correct code patterns on the official ShellCheck wiki.

Common Shell Scripting Traps Caught by ShellCheck

ShellCheck excels at catching subtle pitfalls that human developers frequently miss. Here are three common examples:

1. Unquoted Variables and Word Splitting (SC2086)

Consider the following line designed to remove files based on user input:

rm $filename

If $filename contains spaces (such as \”Quarterly Budget.csv\”), Bash expands this into two separate arguments: rm Quarterly and Budget.csv, potentially deleting the wrong files. ShellCheck flags this immediately:

In backup_script.sh line 14:
rm $filename
   ^-------^ SC2086 (info): Double quote to prevent globbing and word splitting.

2. Legacy Command Substitution (SC2006)

Older shell scripts frequently use backticks for command substitution:

today=`date +%F`

Backticks make nesting commands difficult and obscure nested quotes. ShellCheck advises modern POSIX syntax:

In backup_script.sh line 8:
today=`date +%F`
      ^--------^ SC2006 (style): Use $(...) instead of legacy `...`.

3. Comparing Numbers with String Operators

Using string comparison operators like == or != instead of numeric flags like -eq or -ne inside single brackets ([ ... ]) can cause unexpected logic failures. ShellCheck identifies the type mismatch instantly and supplies the correct numeric operator.

Customising ShellCheck Output and Formats

ShellCheck provides several command-line flags to adapt to different development environments:

• Targeting a Specific Shell Dialect: If your script is written for pure POSIX sh or Dash rather than Bash, enforce that standard using the -s flag:

  shellcheck -s sh deployment.sh

• Filtering by Severity: To ignore minor formatting suggestions and only display critical errors and warnings, use the -S severity switch:

  shellcheck -S warning audit.sh

• Ignoring Specific Warnings: If a specific line requires an intentional, unconventional construct, you can instruct ShellCheck to ignore it by placing a directive comment immediately above the line:

  # shellcheck disable=SC2086
  echo $VAR_WITH_INTENTIONAL_SPLITTING

Integrating ShellCheck into your terminal workflow catches silent syntax errors early, ensuring your Linux automation scripts run reliably and securely across all environments.