Python PDB Debugger Tutorial – Complete Guide with Examples

Python - Debugger (PDB)

Debugging is one of the most important skills for any programmer. While writing code, errors and unexpected behavior are common. To identify and fix these issues efficiently, Python provides a built-in debugging tool called PDB (Python Debugger).

PDB allows you to pause program execution, inspect variables, step through code line by line, and understand how your program is running internally.

In this tutorial, you will learn what PDB is, how to use it, its commands, and real-world debugging examples.

---

What is PDB in Python?

PDB stands for Python Debugger.

It is a built-in module that helps you:

• Pause program execution
• Inspect variables
• Execute code step by step
• Identify logic errors
• Understand program flow

Instead of guessing what went wrong, PDB lets you see inside your code while it runs.

---

Why Use PDB?

PDB is useful for:

• Debugging complex programs
• Fixing logic errors
• Understanding code flow
• Testing small code sections
• Analyzing variables at runtime

It is a powerful tool for developers working on real-world applications.

---

Importing PDB

import pdb

Once imported, you can use debugging functions inside your code.

---

Starting Debugging with PDB

The most common way to start debugging is using:

pdb.set_trace()

This pauses program execution at that line.

---

Simple Example

import pdb

x = 10
y = 20

pdb.set_trace()

result = x + y
print(result)

What happens:

When execution reaches pdb.set_trace():

• Program pauses
• Debugger starts
• You can inspect variables

---

PDB Command Prompt

When debugging starts, you will see a prompt like:

(Pdb)

You can type commands here to control execution.

---

Common PDB Commands

1. n (next)

Execute the next line.

n

---

2. c (continue)

Continue execution until next breakpoint.

c

---

3. s (step)

Step into a function.

s

---

4. p (print variable)

Display variable value.

p x

---

5. l (list code)

Show current code context.

l

---

6. q (quit)

Exit debugger.

q

---

Debugging Example

import pdb

def add_numbers(a, b):
    return a + b

x = 5
y = 10

pdb.set_trace()

result = add_numbers(x, y)
print(result)

In Debug Mode:

You can:

• Inspect x and y
• Step into add_numbers()
• Check return values

---

Using PDB Without Code Changes

You can run PDB directly from terminal:

python -m pdb script.py

This starts debugging from the first line.

---

Setting Breakpoints

Instead of stopping immediately, you can set breakpoints.

import pdb

def multiply(a, b):
    return a * b

pdb.set_trace()

result = multiply(3, 4)
print(result)

---

Conditional Debugging Example

import pdb

for i in range(5):
    if i == 3:
        pdb.set_trace()
    print(i)

Debugger activates only when i == 3.

---

Inspecting Variables in PDB

Inside debugger:

p i
p result
p x + y

You can evaluate expressions directly.

---

Stepping Through Functions

import pdb

def square(n):
    return n * n

pdb.set_trace()

print(square(5))

Use:

• s → enter function
• n → move line by line

---

PDB in Real-World Debugging

PDB is used in:

• Web applications (Flask, Django)
• API development
• Data analysis scripts
• Automation tools
• Machine learning pipelines

It helps locate bugs in complex systems.

---

Example: Bug Fixing

import pdb

def divide(a, b):
    return a / b

x = 10
y = 0

pdb.set_trace()

print(divide(x, y))

You can inspect y before error occurs.

---

Advantages of PDB

• Built into Python
• No installation required
• Powerful debugging control
• Step-by-step execution
• Variable inspection
• Lightweight tool

---

Disadvantages of PDB

• Text-based interface
• Not beginner-friendly initially
• Slower than GUI debuggers
• Requires learning commands

---

Best Practices

1. Use PDB for Debugging Only

Remove pdb.set_trace() after debugging.

---

2. Use Breakpoints Strategically

Place breakpoints near suspicious code.

---

3. Combine with Logging

Use logging for monitoring + PDB for debugging.

---

4. Avoid in Production Code

Never leave debugger in production.

---

PDB vs Print Debugging

Feature	print()	PDB
Control execution	❌	✅
Inspect variables	Limited	Advanced
Step-by-step debugging	❌	✅
Suitable for large projects	❌	✅

---

Summary

Python PDB (Python Debugger) is a powerful tool that allows developers to pause execution, inspect variables, and debug code step by step. It is essential for understanding program behavior and fixing complex bugs.

Key Takeaways

• PDB is Python’s built-in debugger
• Use pdb.set_trace() to start debugging
• Common commands: n, c, s, p, l, q
• Helps inspect variables and program flow
• Useful for complex debugging scenarios
• Should not be used in production code

Mastering PDB will significantly improve your ability to debug and understand Python programs efficiently.