{"title":"Debugging Basics","description":"","content":"Every Python program eventually does something you didn't expect, and the question becomes: how do you find out why? This lesson covers the tools that ship with Python for inspecting a running program, from `print` calls to the built-in `pdb` debugger, plus the third-party debuggers and IDE integrations most engineers reach for in real work. The goal is to stop guessing what your code is doing and start asking it directly.\n\n---\n\n# `print` Debugging vs Real Debuggers\n\n`print` debugging is the universal first move. You add a `print(cart)` next to the line you suspect, rerun, and read the output. It works, it's free, and you can do it without leaving your editor. For a one-line typo in a `total` calculation, it's often the fastest way to find the bug.\n\nThe problem with `print` debugging shows up when the bug is harder. You don't know which value you need to inspect until you've already added prints in the wrong places. You rerun, see the next confusing value, add more prints, rerun again. Each cycle costs you the time to restart the program, replay the failing scenario, and scroll through output. With anything stateful, like a shopping cart that mutates over many calls, prints accumulate into a wall of text where every interesting line looks the same as every other.\n\nA debugger inverts the loop. You stop the program once, at the suspicious line, and then you can ask it anything: print any variable, evaluate any expression, step forward one line at a time, jump up the call stack to see who called this function. The program holds still while you look around. You don't have to know in advance what to inspect.\n\n\n| Situation | Use `print` | Use a debugger |\n| --- | --- | --- |\n| Tiny script, one suspect line | Yes | Overkill |\n| You know exactly what to look at | Yes | Either works |\n| You don't know where the bug is | Slow | Much faster |\n| Bug only happens with complex state | Hard to read | Built for this |\n| Code is in a library you can't easily edit | No good | Set a breakpoint there |\n| Production logs from a server | Logging, not `print` | Post-mortem from a saved traceback |\n| Loop that runs 10,000 times | Floods output | Conditional breakpoint |\n\n\nThe honest answer is that experienced Python developers use both. `print` for fast checks, the debugger when the bug refuses to surrender to prints. The expensive mistake is staying with `print` debugging long after the bug has shown it deserves a debugger.\n\n---\n\n# The `breakpoint()` Builtin\n\nBefore Python 3.7, dropping into the debugger meant typing `import pdb; pdb.set_trace()` at the line you cared about. That's ugly enough that people would forget to remove it, push it to a repo, and ship a debugger trap to production. PEP 553 fixed this with a one-line builtin:\n\n\n```python\ndef apply_discount(cart_total: float, percent: float) -> float:\n discount = cart_total * percent / 100\n breakpoint()\n return cart_total - discount\n```\n\n\nRun the program and execution pauses at `breakpoint()`. You get an interactive `(Pdb)` prompt where you can inspect everything in scope:\n\n\n```shell\n> /Users/dev/shop/discount.py(3)apply_discount()\n-> discount = cart_total * percent / 100\n(Pdb) p cart_total\n99.95\n(Pdb) p percent\n10\n(Pdb) p discount\n9.995\n(Pdb) c\n```\n\n\nThe `c` (continue) command resumes the program. The `p` (print) command shows the value of any expression you can name in the current scope.\n\nThe clever part of `breakpoint()` is what happens under the hood. It looks up the `PYTHONBREAKPOINT` environment variable, defaults to `pdb.set_trace` if it's not set, and calls whatever that variable points to. That gives you three useful behaviors with no code changes:\n\n\n```shell\n# Default: drops into pdb\npython shop.py\n\n# Use ipdb instead (after pip install ipdb)\nPYTHONBREAKPOINT=ipdb.set_trace python shop.py\n\n# Disable all breakpoints (for production or CI)\nPYTHONBREAKPOINT=0 python shop.py\n```\n\n\nSetting `PYTHONBREAKPOINT=0` is the trick that protects you from forgotten `breakpoint()` calls. The function becomes a no-op, the program runs straight through, and CI never hangs waiting for a prompt. Production environments often set this in their startup script as a safety net.\n\nYou can also point it at a custom function. `PYTHONBREAKPOINT=mypkg.my_debugger` will import `mypkg` and call `my_debugger()` at every `breakpoint()`. Teams sometimes use this to route into web-based debuggers or to capture state for offline analysis.\n\n\n> **INFO**\n>\n> **Cost:** `breakpoint()` has zero overhead when `PYTHONBREAKPOINT=0`. It's safe to leave a `breakpoint()` call in dev code if your production environment sets that variable, but the cleaner habit is to remove them before commit.\n\n\n---\n\n# Core `pdb` Commands\n\nOnce you're at the `(Pdb)` prompt, the program is paused and you control what happens next. `pdb` has about thirty commands. You only need a dozen for ninety percent of debugging work.\n\n\n| Command | Short | What it does |\n| --- | --- | --- |\n| `list` | `l` | Show 11 lines of source around the current line |\n| `longlist` | `ll` | Show the full source of the current function |\n| `next` | `n` | Run the current line. Don't step into function calls |\n| `step` | `s` | Run the current line. Step into any function calls |\n| `continue` | `c` | Run until the next breakpoint or program end |\n| `return` | `r` | Run until the current function returns |\n| `until` | `unt` | Run until a line number greater than the current one |\n| `break` | `b` | Set a breakpoint (by line number, function, or condition) |\n| `clear` | `cl` | Remove a breakpoint by number |\n| `print` | `p` | Print the value of an expression |\n| `pp` | | Pretty-print (good for big dicts and lists) |\n| `where` | `w` | Show the current call stack |\n| `up` | `u` | Move one frame up the stack (toward the caller) |\n| `down` | `d` | Move one frame down (toward the current function) |\n| `args` | `a` | Print the current function's arguments |\n| `!` | | Run any Python statement in the current scope |\n| `quit` | `q` | Abort the program |\n| `help` | `h` | List commands, or `h cmd` for one command |\n\n\nThe split that confuses people first is `n` versus `s`. Both run the current line, but `n` treats a function call as a single step (you see the call complete, then stop at the next line in the current function), while `s` enters the function and stops at its first line. Use `n` when you trust the function you're calling. Use `s` when you suspect it.\n\nHere's a session walking through a buggy cart total. The code:\n\n\n```python\n# cart.py\ndef line_total(price: float, quantity: int) -> float:\n return price + quantity # bug: should be price * quantity\n\ndef cart_total(items: list[tuple[str, float, int]]) -> float:\n total = 0.0\n for name, price, quantity in items:\n total += line_total(price, quantity)\n return total\n\nif __name__ == \"__main__\":\n cart = [\n (\"headphones\", 59.99, 1),\n (\"cable\", 9.99, 2),\n ]\n breakpoint()\n print(f\"Cart total: ${cart_total(cart):.2f}\")\n```\n\n\nRun it:\n\n\n```shell\n> /Users/dev/shop/cart.py(14)()\n-> print(f\"Cart total: ${cart_total(cart):.2f}\")\n(Pdb) l\n 9 return total\n 10\n 11 if __name__ == \"__main__\":\n 12 cart = [\n 13 (\"headphones\", 59.99, 1),\n 14 -> (\"cable\", 9.99, 2),\n 15 ]\n 16 breakpoint()\n 17 -> print(f\"Cart total: ${cart_total(cart):.2f}\")\n(Pdb) s\n--Call--\n> /Users/dev/shop/cart.py(4)cart_total()\n-> def cart_total(items: list[tuple[str, float, int]]) -> float:\n(Pdb) n\n> /Users/dev/shop/cart.py(5)cart_total()\n-> total = 0.0\n(Pdb) n\n> /Users/dev/shop/cart.py(6)cart_total()\n-> for name, price, quantity in items:\n(Pdb) n\n> /Users/dev/shop/cart.py(7)cart_total()\n-> total += line_total(price, quantity)\n(Pdb) p name, price, quantity\n('headphones', 59.99, 1)\n(Pdb) s\n--Call--\n> /Users/dev/shop/cart.py(1)line_total()\n-> def line_total(price: float, quantity: int) -> float:\n(Pdb) n\n> /Users/dev/shop/cart.py(2)line_total()\n-> return price + quantity\n(Pdb) p price + quantity\n60.99\n(Pdb) p price * quantity\n59.99\n```\n\n\nAt that last line, the bug is obvious. The function adds when it should multiply, so a single-quantity item produces the right answer by accident, but a quantity of 2 will not. Without the debugger, you'd be guessing where the bug lives. With it, you stepped from the outer call into the inner function and watched the wrong arithmetic happen.\n\nA few more habits that pay off:\n\n- `w` (where) shows the call stack. Use it to figure out who called the function you're stuck in. `u` and `d` walk up and down the stack so you can inspect the caller's variables.\n- `a` (args) prints the current function's arguments. Useful when you stepped in with `s` and want a quick reminder of what was passed.\n- `!` runs any Python in the current scope. `!cart.append((\"milk\", 3.49, 1))` mutates the live cart so you can keep debugging without restarting.\n- `pp` pretty-prints. `pp orders` on a list of fifty order dicts is a lot more readable than `p orders`.\n- `ll` (longlist) shows the entire current function rather than 11 lines. Use it when you've lost track of where you are.\n\n---\n\n# Setting Breakpoints from Inside `pdb`\n\nCalling `breakpoint()` is the easiest way to enter the debugger. Once you're inside it, the `b` (break) command lets you set more breakpoints without editing the source.\n\n\n```shell\n(Pdb) b cart.py:7\nBreakpoint 1 at /Users/dev/shop/cart.py:7\n(Pdb) b line_total\nBreakpoint 2 at /Users/dev/shop/cart.py:1\n(Pdb) b cart.py:7, quantity > 1\nBreakpoint 3 at /Users/dev/shop/cart.py:7\n```\n\n\nThree forms in three lines:\n\n1. `b cart.py:7` breaks at line 7 every time it runs.\n2. `b line_total` breaks at the first line of the function `line_total`.\n3. `b cart.py:7, quantity > 1` is a conditional breakpoint. It only pauses when the expression after the comma is true. This is the form that turns a hopeless \"the bug only happens on item 4217\" problem into a one-step investigation.\n\n`b` with no argument lists all current breakpoints. `cl 2` clears breakpoint 2. `disable 2` turns it off without removing it, and `enable 2` turns it back on.\n\nYou can also attach commands to a breakpoint, so it does something automatically every time it hits:\n\n\n```shell\n(Pdb) b line_total\nBreakpoint 1 at /Users/dev/shop/cart.py:1\n(Pdb) commands 1\n(com) p price, quantity\n(com) c\n(com) end\n```\n\n\nNow every time `line_total` is called, `pdb` prints `price, quantity` and continues without prompting. The result is a targeted trace, with only the values you want, without permanent edits to the source.\n\n---\n\n# Post-Mortem Debugging\n\nThe bugs that hurt are the ones you can't reproduce on demand. The program crashed, you have a traceback, and you need to look around inside the crashed state. `pdb` has a post-mortem mode for exactly this.\n\nThree ways to use it:\n\n\n```shell\n# Run a script and drop into pdb at the first uncaught exception.\npython -m pdb shop.py\n\n# Same idea, but only if the script crashes (interactive shell).\npython -c \"import pdb, shop; pdb.run('shop.main()')\"\n\n# After a crash in a REPL, inspect the last traceback.\npython\n>>> import shop\n>>> shop.main()\nTraceback (most recent call last):\n ...\nZeroDivisionError: division by zero\n>>> import pdb\n>>> pdb.pm()\n```\n\n\n`python -m pdb shop.py` is the workhorse. It loads the script but pauses before the first line, so you can set breakpoints anywhere with `b` and then `c` to run. If the script then raises an uncaught exception, you land at a `(Pdb)` prompt inside the failing frame with all local variables still alive.\n\nInside your own code, you can install the same behavior with `sys.excepthook`:\n\n\n```python\nimport sys\nimport pdb\n\ndef info(exc_type, value, tb):\n pdb.post_mortem(tb)\n\nsys.excepthook = info\n```\n\n\nAfter that, any uncaught exception drops you straight into the debugger. This is a development-only trick. Don't ship it.\n\n`pdb.pm()` (short for \"post-mortem\") works on the last exception that left a traceback in `sys.last_traceback`. The REPL keeps it around after an interactive crash, so the workflow becomes: run the failing code, see the traceback, call `pdb.pm()`, look around.\n\n\n> **INFO**\n>\n> **Cost:** Post-mortem debugging holds the entire stack of the crashed frame in memory, including every local variable and every reference they hold. For a script this is nothing. For a server processing big datasets, watch out: a held traceback can keep gigabytes alive.\n\n\n---\n\n# `ipdb`, `pudb`, and the `pdb` Improvements in 3.13\n\nThe built-in `pdb` is plain. No syntax highlighting, no tab completion on Python expressions by default, no second window for variables. For long debugging sessions, the alternatives are worth knowing.\n\n`ipdb` is `pdb` running on top of IPython. After `pip install ipdb`, you get the same commands plus colored output, real tab completion, history across sessions, and IPython-style `?` for help on any object. Drop in with `import ipdb; ipdb.set_trace()` or wire up `PYTHONBREAKPOINT=ipdb.set_trace` so plain `breakpoint()` routes there. If you spend much time in `pdb`, `ipdb` is a small upgrade that pays off the first day.\n\n`pdb++` (the package is named `pdbpp`) replaces `pdb` outright. Same import path, same commands, but with sticky source display (the source window stays visible while you step), syntax highlighting, and smarter completion. It tends to be either loved or quietly removed depending on whether you like its defaults.\n\n`pudb` is the curses-based full-screen debugger. After `pip install pudb`, `import pudb; pudb.set_trace()` opens a TUI with separate panes for source, variables, breakpoints, and stack. It runs in a regular terminal, which makes it useful over SSH where a graphical IDE isn't available. The keybindings take a few minutes to learn, but for stepping through a long stack of frames it's the most readable of the terminal options.\n\nPython 3.13 brought a sizable upgrade to the built-in `pdb` itself. The two highlights:\n\n1. Tab completion now works for Python expressions, not just commands. `cart.` then Tab lists the attributes.\n2. Multi-line input is supported. You can paste a small block of Python and run it without stitching it into one line with semicolons.\n\nThere's also `python -m pdb -m mypkg`, which runs a module under `pdb` the same way you'd run it under Python normally. Before 3.7, you had to find the module's file path yourself.\n\n\n| Tool | Install | Best for |\n| --- | --- | --- |\n| `pdb` | Built in | Quick checks, any machine |\n| `ipdb` | `pip install ipdb` | Daily use, colors and completion |\n| `pdb++` | `pip install pdbpp` | Sticky source view, opinionated defaults |\n| `pudb` | `pip install pudb` | TUI over SSH, full-screen panes |\n| VS Code / PyCharm | IDE feature | Variable panes, click-to-set breakpoints |\n\n\n---\n\n# IDE Debuggers\n\nIDEs like VS Code and PyCharm wrap a debugger backend in a graphical interface. You click in the gutter to set a breakpoint, run the program in debug mode, and the editor pauses on the marked line with a panel showing every local variable, the call stack, watch expressions, and a console that runs in the same scope as the paused frame.\n\nThe big advantages over a terminal debugger are visibility and discoverability. You see ten variables at once instead of typing `p` ten times. The stack is a clickable list, so jumping to the caller is one click rather than `w` followed by `u`. Stepping into a third-party library is a click on a button. Conditional breakpoints, hit counts, and log-point breakpoints (which print a message without pausing) are all configured through small forms instead of typed-in command syntax.\n\nMost modern IDE debuggers speak the Debug Adapter Protocol (DAP), a JSON-RPC wire format originally designed for VS Code. The IDE is the client, a debug adapter is the server, and the actual debugging library (`debugpy` for Python) is what drives the running program. The decoupling matters in practice: any editor that speaks DAP can debug Python with `debugpy`, including Neovim and Emacs. PyCharm has its own backend, but the user experience is similar.\n\nWhen IDE debugging beats `pdb`:\n\n- Long sessions where you want to see ten variables update as you step.\n- Debugging into a third-party library you didn't write, where source navigation in a terminal is painful.\n- Remote debugging a running server. Attach the IDE to a `debugpy` server in the container, set breakpoints, and step through.\n- Onboarding. New engineers tend to learn an IDE debugger faster than a typed-command one.\n\nWhen `pdb` still wins:\n\n- SSH sessions with no port forwarding.\n- One-off scripts where launching the IDE takes longer than the bug deserves.\n- CI failures. Drop a `breakpoint()` in a test, run the failing test locally, and you're inside the failure in seconds.\n\nThere's no rule that says you have to pick one. Most experienced Python developers use the IDE debugger for complex bugs and `breakpoint()` for quick checks.\n\n---\n\n# Reading a Python Traceback\n\nThe traceback is the report Python prints when an uncaught exception kills the program. It's the most important piece of evidence you'll ever read about a Python bug, and the order it prints in is the opposite of what most people expect.\n\nHere's a small program that fails:\n\n\n```python\ndef line_total(price: float, quantity: int) -> float:\n return price * quantity\n\ndef cart_total(items):\n total = 0.0\n for name, price, quantity in items:\n total += line_total(price, quantity)\n return total\n\ndef main():\n cart = [\n (\"headphones\", 59.99, 1),\n (\"cable\", \"9.99\", 2),\n ]\n print(f\"Cart total: ${cart_total(cart):.2f}\")\n\nmain()\n```\n\n\nRunning it produces:\n\n\n```shell\nTraceback (most recent call last):\n File \"/Users/dev/shop/cart.py\", line 16, in \n main()\n File \"/Users/dev/shop/cart.py\", line 14, in main\n print(f\"Cart total: ${cart_total(cart):.2f}\")\n ^^^^^^^^^^^^^^^^\n File \"/Users/dev/shop/cart.py\", line 7, in cart_total\n total += line_total(price, quantity)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File \"/Users/dev/shop/cart.py\", line 2, in line_total\n return price * quantity\n ~~~~~~^~~~~~~~~~\nTypeError: can't multiply sequence by non-int of type 'float'\n```\n\n\nThe order is oldest call at the top, most recent at the bottom. The exception itself is on the last line. The rule of thumb most experienced developers follow is read the last line first, then walk up the stack until you find a frame in your own code.\n\nIn this traceback, the last line is the actual error: a `TypeError` trying to multiply a string by a float. The line above it shows the failing expression with carets pointing at `price * quantity`. The frame above shows that `line_total` was called from `cart_total`, which was called from `main`, which was called at module top level. The carets (added in Python 3.11) point at the exact subexpression that failed, which usually narrows the bug to one piece of one line. Here, the bug is that `(\"cable\", \"9.99\", 2)` has a string price, and the multiply fails when that value reaches `line_total`.\n\nWhen one exception is raised while handling another, Python prints both, separated by a phrase:\n\n\n```shell\nTraceback (most recent call last):\n File \"shop.py\", line 3, in load\n raise FileNotFoundError(\"orders.json\")\nFileNotFoundError: orders.json\n\nDuring handling of the above exception, another exception occurred:\n\nTraceback (most recent call last):\n File \"shop.py\", line 8, in \n load()\n File \"shop.py\", line 5, in load\n raise RuntimeError(\"could not load orders\") from None\nRuntimeError: could not load orders\n```\n\n\nTwo phrases to watch for:\n\n- `During handling of the above exception, another exception occurred:` means the second exception was raised inside the `except` block of the first. The two are unrelated chains, but Python prints both because losing the original would hide context.\n- `The above exception was the direct cause of the following exception:` means the code explicitly chained with `raise NewError(...) from original`. The two exceptions are connected on purpose.\n\nReading chains is the same skill: start at the bottom, walk up. The most recent exception is the one Python actually failed on. The earlier one tells you what triggered it.\n\n\n> **INFO**\n>\n> **Cost:** Tracebacks hold references to every frame's local variables until they're garbage-collected. Keeping a traceback alive in a long-running process (assigning it to a module-level variable, for example) can leak large objects. Use `traceback.format_exc()` to get a string copy if you need to store it.\n\n\n---\n\n# Debugging Strategies\n\nThe tools are only half the job. The other half is the strategy you use to apply them. A few habits that turn into hours saved:\n\n**Build a minimal reproduction.** If the bug shows up in a production-scale system, try to reproduce it with the smallest possible inputs. Strip away services, mocks, frameworks, fixtures, until you have the smallest program that still fails. The bug usually gets obvious somewhere in that stripping process. If it doesn't, you now have a tiny case that's easy to share and easy to debug.\n\n**Bisect the change.** If \"it worked yesterday and broke today,\" let Git find the breaking commit for you:\n\n\n```shell\ngit bisect start\ngit bisect bad HEAD\ngit bisect good v1.2.0\n# git checks out a commit; you run your repro; you say `good` or `bad`\n# git keeps narrowing until it identifies the breaking commit\n```\n\n\nYou can also bisect inside one file. Comment out half the function, run the failing case. If it still fails, the bug is in the other half. Repeat.\n\n**Read the error message first, twice, slowly.** A surprising amount of debugging time is wasted because the engineer started fixing the code before finishing reading the traceback. `KeyError: 'price'` is telling you the exact thing that went wrong. Believe it. Don't start by changing unrelated code.\n\n**Rubber-duck the code.** Explain what each line does, out loud, to a colleague or an actual rubber duck. The act of forcing yourself to put the program's behavior into words exposes the place where your mental model and the actual code disagree. That's usually the bug.\n\n**Form a hypothesis, then check it.** Don't randomly add `print` calls. Decide what you think is happening, predict what a specific variable should be at a specific line, then check. If you were right, you've ruled out a hypothesis. If you were wrong, you've found a real clue. Either way, you've made progress, which is more than blind printing gives you.\n\n**Know when to use `logging` instead.** Logging is the right answer when the program runs unattended (production, scheduled jobs, server processes) or when you need a record of behavior over time. `logging.debug(\"processing order %s\", order.id)` left in the code costs almost nothing when the log level is INFO, and is invaluable when the bug reappears next month. Breakpoints win for interactive bugs you can reproduce on your laptop right now. Logs win for everything else.\n\n**Use `faulthandler` for segfaults.** If your Python code dies with no traceback (a segfault from a C extension, for example), `pdb` is no help; the interpreter is dead. `faulthandler` is a standard-library module that installs a signal handler to dump a Python traceback when the process crashes:\n\n\n```python\nimport faulthandler\nfaulthandler.enable()\n```\n\n\nYou can also enable it from the command line with `python -X faulthandler script.py` or by setting `PYTHONFAULTHANDLER=1`. The output is less detailed than a normal traceback, but it points you at the Python line that triggered the crash, which is usually enough to find the offending C extension call.\n\n**`sys.settrace` for custom tracing.** For one-off needs that don't fit `pdb`, `sys.settrace(func)` installs a callback Python invokes for every executed line. It's the same mechanism `pdb` itself uses. Most engineers never reach for it, but it's there when you need to build a custom tracer, profiler, or coverage tool.\n\n---\n\n# A Debugging Decision Tree\n\nHere's the rough decision tree most experienced Python developers run through when something breaks:\n\n\n```mermaid\nflowchart TD\n BUG[Something broke]:::cyan\n REPRO{Can you
reproduce it?}:::orange\n LOGS[Read logs and
tracebacks]:::orange\n SMALL{Tiny script or
known line?}:::orange\n PRINT[Use print or
logging.debug]:::green\n INTERACTIVE{Interactive bug
on your machine?}:::orange\n BREAKPOINT[Drop in breakpoint and
step with pdb or ipdb]:::green\n SERVER{Long-running
server or job?}:::orange\n LOGGING[Add structured
logging at DEBUG]:::green\n CRASH{Crash with
no traceback?}:::orange\n FAULT[Enable faulthandler
then rerun]:::red\n POST[Use pdb post-mortem
or pdb.pm]:::teal\n\n BUG --> REPRO\n REPRO -->|No| LOGS\n LOGS --> POST\n REPRO -->|Yes| SMALL\n SMALL -->|Yes| PRINT\n SMALL -->|No| INTERACTIVE\n INTERACTIVE -->|Yes| BREAKPOINT\n INTERACTIVE -->|No| SERVER\n SERVER -->|Yes| LOGGING\n SERVER -->|No| CRASH\n CRASH -->|Yes| FAULT\n CRASH -->|No| BREAKPOINT\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe tree isn't a strict procedure. It's a starting point for picking the tool that fits the shape of the bug, so you don't reflexively reach for `print` every time. The pattern that matters: reproduce first, then pick the tool that gives you the most information for the least friction.\n\n---\n\n# Quiz","pageType":"python"}

Debugging Basics

Get Premium