How to Debug Python Code in 2026: Tools and Techniques That Actually Work
A practical Python debugging workflow covering reproduction, isolation, inspection, fixing and verifying with tests.
Every Python developer hits bugs, from a typo that stops a script cold to a logic error that quietly produces wrong results for weeks. The difference between a frustrating afternoon and a quick fix is rarely talent. It is method. Developers who debug well follow a repeatable process, use the right tool for the size of the problem, and prove the fix before moving on. This guide sets out that process.
Direct answer: To debug Python code, first reproduce the bug reliably, then isolate the smallest case that still fails, inspect the actual values with a debugger or logging, fix the root cause rather than the symptom, and verify the fix with a test. Print statements work for small scripts, pdb and IDE debuggers work better for complex code, and logging is the right choice for code that runs unattended.
A Repeatable Debugging Workflow
Random changes and hopeful reruns waste time and often hide the real problem. A short workflow keeps you in control. It works for a 50 line script and for a large web application, because the steps scale even when the codebase does not.
- Reproduce. Run the code and record the exact input, command and error. If you cannot reproduce it, you cannot prove you fixed it. Note the Python version, the operating system and any environment variables that matter.
- Isolate. Cut the failing case down. Remove unrelated code, simplify the input and use a minimal example. If a bug disappears when you remove a section, that section is involved. Binary search through the code by disabling halves until the failure narrows to one area.
- Inspect. Look at actual values, not assumed values. Check variable contents, function arguments and return values at the point of failure. Most bugs are a wrong value in a place the developer assumed was correct.
- Fix the cause. Change the code that creates the wrong value, not code downstream that merely hides it. A fix that only patches one symptom will fail again with slightly different input.
- Verify. Rerun the original failing case, then run related tests. Add a regression test so the same bug cannot return silently in a future change.
Print Debugging Done Well
Print debugging gets mocked, but it is fast, available everywhere and often enough for a small script. The trick is to print useful information, not just markers. A bare print saying “here” tells you execution reached a line. A print showing a variable name, its value and its type tells you what is actually happening.
Use f-strings to make output readable, for example printing both a variable name and its value in one line. Print at boundaries: where data enters a function, where it is transformed, and where it leaves. If a loop misbehaves, print the iteration count and the current item for the first few iterations, not for ten thousand of them. Too much output hides the signal just as surely as too little.
Know when to stop printing. If you are adding a sixth print statement, switching to a debugger will be faster. Print statements also have a habit of being left in production code, where they slow programs and leak data into logs. Treat prints as temporary scaffolding and remove them once the bug is found. If you are still building Python fundamentals, this guide to how to learn Python covers the basics that make debugging far less painful.
pdb and IDE Debuggers
Python ships with pdb, a command line debugger documented in the Python docs. You can start it with python -m pdb script.py or drop breakpoint() into your code, which pauses execution at that line in Python 3.7 and later. Once paused, you can inspect variables, step through code line by line, step into functions, and continue execution. The commands are short: n for next line, s to step into a call, c to continue, and p to print a value.
IDE debuggers offer the same power with a visual interface. VS Code, with the Python extension, and PyCharm both let you click beside a line to set a breakpoint, then inspect variables, watch expressions and the call stack while the program is paused. Conditional breakpoints are especially useful: they pause only when a condition is true, for example when a counter reaches a specific value or a variable becomes negative. That saves you from stepping through hundreds of normal iterations to reach one bad one.
Debuggers also show the call stack, the chain of function calls that led to the current line. Reading the stack often reveals that a function received bad input from a caller several levels up, which changes where the fix belongs. When a bug only appears in a specific environment, check that environment first. Many Windows setup problems are not code bugs at all, as this guide to fix pip not recognized on Windows 11 shows. Confirming the interpreter, the active environment and the installed packages can save a long debugging session.
Logging Instead of Printing
For code that runs on a server, on a schedule or in production, printing is not enough. Python’s built in logging module, also documented in the Python docs, lets you record messages at levels such as DEBUG, INFO, WARNING and ERROR, and send them to a file or a monitoring system instead of the console.
Good logging records context: what happened, which record was involved, and which values mattered. Log at system boundaries and when external services are called. Avoid logging passwords, tokens or personal data.
Common Python Errors and How to Read Tracebacks
A traceback is Python telling you exactly where things went wrong, if you read it in the right order. Start at the bottom, where the error type and message live. Then read upward through the call stack to find the last line of your own code. Library frames above it show the path, but the fix usually belongs in your code.
| Error | What it usually means | First thing to check |
|---|---|---|
| NameError | A name is not defined in this scope | Spelling, import, and whether the variable was assigned before use |
| TypeError | An operation was applied to the wrong type | The actual type of each argument, printed at the failure point |
| ValueError | The type is right but the value is not acceptable | Input data and any conversion, such as int() on a string |
| IndexError | A list or sequence index is out of range | The length of the sequence and the index value |
| KeyError | A dictionary key does not exist | Whether the key was set, and whether .get() is safer here |
| AttributeError | An object has no such attribute or method | The object’s actual type, which may be None |
| IndentationError | Indentation is inconsistent | Mixed tabs and spaces, and block structure |
AttributeError on None is a frequent culprit. It usually means a function returned None unexpectedly, perhaps because it had no return statement on some path. Tracing back to where that None came from is more useful than guarding every later use. Similarly, a TypeError often points to data arriving in a different shape than expected. Check the data source, not just the line that crashed.
Environment issues can look like code errors too. If an import fails in one terminal but works in another, you are probably running a different interpreter or environment. This overview of Python virtual environments explained is worth reading before you reinstall packages in desperation. Confirm which Python is running and which environment is active before changing code.
Testing a Fix So It Does Not Regress
A fix is not done when the error message disappears. It is done when the original case passes, neighbouring cases still pass, and a test guards the behaviour. Write a small test that reproduces the bug first, watch it fail, then apply the fix and watch it pass. That order matters: a test that never failed may not actually cover the bug.
Use pytest for most projects in 2026. It is adopted and its failure output shows values clearly. For a bug in one function, a single unit test is enough. For a bug spanning several components, add an integration test with realistic data. Run the full test suite before declaring the fix complete, because fixes in shared code can break other features.
Frequently Asked Questions
What is the best way to debug Python code as a beginner?
Start with the workflow in this guide: reproduce the bug, read the traceback from the bottom up, and inspect actual values. Use print statements for small scripts and move to the VS Code or PyCharm debugger once programs grow. Learning to read tracebacks early will save more time than any single tool, because every later technique builds on that skill.
Should I use print statements or a debugger?
Use prints for quick checks in small scripts, and a debugger for anything complex, intermittent or hard to reproduce. A debugger lets you pause execution, inspect any variable and step through code without editing it, which is faster once you are past the basics. Logging replaces both for production code, where you cannot pause execution or watch a console.
How do I use pdb in Python?
Add breakpoint() where you want to pause, then run your script normally. At the pdb prompt, use n for the next line, s to step into a call, c to continue, and p plus a variable name to inspect a value. The Python docs cover the full command list.
Why does my Python code work on one computer but not another?
Different Python versions, different installed packages, or a different active virtual environment are the usual causes. Check the Python version and the environment on both machines, compare installed packages, and confirm how the script is launched. Path differences, especially on Windows, and missing environment variables also cause code that runs fine on one machine to fail on another.
How can I find a bug that only happens sometimes?
Intermittent bugs usually depend on data, timing or order. Log inputs and key values so you can replay the failing case, add conditional breakpoints that pause only on suspicious values, and look for shared state, randomness without a seed, or dependence on dictionary ordering. Once you can reproduce it reliably, even with a large input file, the normal workflow of isolate, inspect and verify applies.
Conclusion
Good Python debugging is a habit, not a trick. Reproduce the bug, isolate the smallest failing case, inspect real values instead of assumed ones, fix the root cause, and prove the fix with a test. Print statements, pdb, IDE debuggers and logging each have a place, and choosing the right one for the situation saves time. Build that workflow into every bug you meet, and debugging stops feeling like guesswork and starts feeling like ordinary, solvable work, step by step, every time.
