Debugging bash scripts with the bashdb debugger

Sometimes when I have a problem with a bash script I want the ability to run each line of the script one by one to see what is wrong. There is a debugger called bashdb that can be used in this way. It behaves similarly to gdb (used for debugging C and C++ programs) and pdb (used for debugging Python programs).

How to install bashdb

First you need to determine what version of bash you are running, since you need to use a corresponding version of bashdb:

# bash --version
GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)

This version of bash is 5.1.16, so we need a bashdb version 5.1.x. Let’s download it:

NOTE: The following commands are written for an Ubuntu- or Debian-based Linux distribution. Also, you may need to prefix some commands with sudo to avoid permission errors.

# apt-get update
# apt-get install git -y
# git clone bashdb-code
# cd bashdb-code/
# git checkout bash-5.1

For bashdb >= 5.1.x, you’ll need to build the configure and bashdb files:

# apt-get update
# apt-get install autoconf -y  # to run
# apt-get install binutils -y  # to install "strings" tool, for
# apt-get install make -y  # to install "make" tool
# apt-get install texinfo -y  # to install "makeinfo" tool, for make
# ./

You should now have a bashdb file in the current directory:

# ls | grep bashdb

(Optional) If you have root permissions, you can install bashdb:

# make install

How to run bashdb

Let’s create an example script to debug:

# cat << EOF > /tmp/
echo 1
echo 2
echo 3
echo 4

If you did install bashdb in the step above, start the debugger on a Bash script at /tmp/ with:

# bash --debugger /tmp/ 
1:  echo 1

If you did not install bashdb, you can run the debugger by calling the bashdb script manually:

# bash ./bashdb /tmp/ 
1:  echo 1

Common commands in bashdb

See all debugger commands using help:

bashdb<0> help
Available commands:
  action     condition  edit     frame    load     run     source  unalias  
  alias      continue   enable   handle   next     search  step    undisplay
  backtrace  debug      eval     help     print    set     step+   untrace  
  break      delete     examine  history  pwd      shell   step-   up       
  clear      disable    export   info     quit     show    tbreak  watch    
  commands   display    file     kill     return   signal  trace   watche   
  complete   down       finish   list     reverse  skip    tty   

Readline command line editing (emacs/vi mode) is available.
Type "help" followed by command name for full documentation.

See where you are in the script using list:

bashdb<1> list
  1: => echo 1
  2:    echo 2
  3:    echo 3
  4:    echo 4

You can step over the current line using next or n:

bashdb<3> next
2:  echo 2
bashdb<4> list
  1:    echo 1
  2: => echo 2
  3:    echo 3
  4:    echo 4

You can step into the current line using step or s. This is useful to enter into a function call or a line that uses source to call another script:

bashdb<6> step
3:  echo 3
bashdb<7> list
  1:    echo 1
  2:    echo 2
  3: => echo 3
  4:    echo 4

You can step out of the current function with finish.

Other common commands include:

  • eval STATEMENT - Run a statement.
    • Example: eval X=1
  • print EXPR - Print an expression, such as a variable.
    • Example: print $X
  • break - Set a breakpoint.
    • Example: break 3 (set breakpoint on line 3)
    • Example: break /tmp/ (set breakpoint on line 4 of file /tmp/hello)
  • continue, cont, c - Step continuously until a breakpoint is hit or the script ends.
  • exit - Stop the script and exit the debugger.