Debug a Python Script from the Terminal with pdb3.12

You will run a Python 3.12 program under the standard debugger, stop at a useful line, inspect its variables, step over code and leave the session cleanly. The installed command is a small wrapper around Python's pdb module, so this needs no package beyond the Python installation already on the machine.

Allow about 15 minutes for the first run. You need a shell, Python source that you can run, and permission to read that source. These examples do not need elevated privileges. Run them as the account that owns the project: using sudo can change the environment and hide the problem you are trying to inspect.

Checkpoint: make a reproducible example

Start with a small program so the debugger output is easy to recognise. This example deliberately divides by zero when the supplied value is zero.

mkdir -p /tmp/pdb-demo
cat > /tmp/pdb-demo/calculate.py <<'PY'
def ratio(total, count):
    return total / count

value = ratio(10, 0)
print(value)
PY
cd /tmp/pdb-demo
python3.12 calculate.py

The ordinary run ends with a traceback containing ZeroDivisionError. The file is temporary and the command changes nothing outside /tmp/pdb-demo. If you are debugging a real project, substitute its path from this point onwards.

1. Start pdb3.12 on the script

Pass the script as the first non-option argument. The debugger stops before the first executable line, which gives you a chance to set a breakpoint before the program runs.

cd /tmp/pdb-demo
pdb3.12 calculate.py

You should see a prompt similar to this:

> /tmp/pdb-demo/calculate.py(1)<module>()
-> def ratio(total, count):
(Pdb)

The exact path and line display can vary. The (Pdb) prompt is the checkpoint: debugger commands are entered there, not at your normal shell prompt. Type help for the command list or help break for one command's help.

2. Set a breakpoint and continue

Set a breakpoint on the division line, then let the program run. Breakpoints can name a line in the current file or a function. The b abbreviation means break.

(Pdb) break 2
Breakpoint 1 at /tmp/pdb-demo/calculate.py:2
(Pdb) continue
> /tmp/pdb-demo/calculate.py(2)ratio()
-> return total / count
(Pdb)

At this point the function has been entered but the division has not yet executed. To check what is about to happen, print the arguments:

(Pdb) p total
10
(Pdb) p count
0

p expression evaluates an expression in the current stack frame. pp expression is useful for a larger value because it pretty-prints the result. Evaluation is real Python code: avoid calling functions that mutate data or contact external services merely to inspect them.

3. Move through the code without losing your place

Use next to execute the current line and stop at the next line in the same function. Use step when you want to enter a called function. Use list to show nearby source and where to show the call stack.

(Pdb) list
  1  def ratio(total, count):
  2 B->    return total / count
  3
(Pdb) where
  /tmp/pdb-demo/calculate.py(4)<module>()
-> value = ratio(10, 0)
  /tmp/pdb-demo/calculate.py(2)ratio()
-> return total / count

In the listing, the arrow marks the current line and B identifies a breakpoint. If the next statement is an ordinary call, next runs that call without stopping inside it; step enters it. A blank line repeats the last debugger command, so be careful after a command that resumes execution.

4. Inspect a failure after it happens

Continue from the breakpoint. The division now raises the exception and pdb enters a post-mortem session:

(Pdb) continue
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
Uncaught exception. Entering post mortem debugging
> /tmp/pdb-demo/calculate.py(2)ratio()
-> return total / count
(Pdb)

Use p, where and up or down to examine the failing frame and its callers. The debugger does not repair the exception. It lets you confirm the state that caused it. If you need a repeatable stop inside application code, add breakpoint() temporarily, or use import pdb; pdb.set_trace() where compatibility with older Python versions matters.

5. Leave the session and remove temporary changes

Use quit when you want to abort the debugged program. This is the important safety boundary: unlike continue, quit stops the target immediately. If the program has already finished, pdb may offer to restart it while preserving breakpoints; answer with quit if you are done.

(Pdb) quit

Remove a breakpoint without deleting the source:

(Pdb) clear 1
Deleted breakpoint 1

If you inserted breakpoint() or pdb.set_trace() into a real file, remove that line before committing or deploying. To remove only the demonstration directory, use this exact path after checking that it contains no files you need:

rm -rf -- /tmp/pdb-demo

This last command is destructive, although its scope is limited to the example directory. Do not adapt it by replacing the path with a project directory. If you want to keep the example, skip the command; no system rollback is needed because pdb itself has not changed your files.

Options that prevent common surprises

The installed pdb3.12 accepts -c or --command to run an initial debugger command, and -m to debug a module rather than a file. For example, stop at the first line of a module:

pdb3.12 -m package.module

For a quick non-interactive run that continues until an exception, use:

pdb3.12 -c continue calculate.py

Be aware that the command-line debugger reads .pdbrc files from your home directory and the current directory before commands supplied with -c. Those files can set breakpoints, run commands or continue execution. If a session starts somewhere unexpected, inspect both files before trusting its behaviour. Do not put secrets in a .pdbrc: debugger expressions can print them.

The module option is not interchangeable with a filesystem path. Use -m package.module for an importable module and a filename for a script. Arguments after the target become the debugged program's arguments, so quote values containing spaces in the normal shell way.