Summarize this article with:
Debugging in PyCharm is the process of identifying and fixing runtime errors in Python code using JetBrains’ built-in debugger tools.
You need this when your script produces unexpected output, crashes without clear error messages, or behaves differently than intended.
This guide covers 10 steps requiring approximately 15 minutes and basic familiarity with PyCharm’s interface.
The Debug tool window gives you direct access to variable inspection, stepping controls, and the debug console.
Unlike print statement debugging, PyCharm’s debugger lets you pause execution at any point and examine the complete program state.
How to Debug in PyCharm
Before you start a debug session, make sure you have:
- PyCharm Community Edition 2023.1 or later (Professional works too)
- Python interpreter 3.8+ configured in your project
- A Python script or project ready for code execution
- Basic understanding of running Python code in PyCharm
Time estimate: 10-15 minutes for your first debugging session.
Skill level: Beginner to intermediate Python developers.
Step One: How Do You Set a Breakpoint in PyCharm?
A breakpoint tells the debugger exactly where to pause your program so you can inspect variable values and execution flow.
Click the gutter area (the gray strip next to line numbers) on any executable line of code. A red dot appears immediately.
Keyboard shortcut: Ctrl+F8 on Windows/Linux, Cmd+F8 on macOS.
Action
- Editor gutter: Click directly on the line number margin where you want execution to stop
- Keyboard alternative: Place your caret on the target line, press Ctrl+F8
- Visual confirmation: Red circle appears in the gutter, entire line gets subtle highlight
Purpose
Breakpoints let you freeze your program at specific moments.
Without them, your code runs straight through and you miss the chance to examine what went wrong.
I usually place my first breakpoint right before the line where I suspect the bug lives. That way I can watch variables change in real time.
Step Two: How Do You Start the Debug Session?
Starting debug mode runs your Python script with the debugger attached, which enables breakpoint suspension and variable inspection.
Click the bug icon in the top toolbar, or right-click your script and select “Debug.”
The Debug tool window opens at the bottom of your screen automatically.
Action
- Debug button location: Green bug icon in the top-right toolbar (next to the Run button)
- Keyboard shortcut: Shift+F9 on Windows/Linux, Ctrl+D on macOS
- Expected result: Debug tool window appears, program runs until first breakpoint
Purpose
Debug mode differs from regular Run mode. It attaches the debugger process to your script.
This connection enables all the inspection features: watches, stepping, expression evaluation.
Your code runs slightly slower in debug mode. That’s normal. The debugger needs to monitor every line.
Step Three: Where Do You Find the Debug Tool Window?
The Debug tool window contains everything you need: the Frames pane, Threads & Variables tab, Console tab, and stepping toolbar.
It appears at the bottom of PyCharm when you start debugging. If hidden, go to View > Tool Windows > Debug.
Action
- Default location: Bottom panel of PyCharm IDE, appears automatically on debug start
- Key sections: Frames pane (left), Variables tab (center), Console tab (right side)
- If window missing: View menu > Tool Windows > Debug, or press Alt+5
Purpose
This window is your debugging command center.
The Frames pane shows your call stack. The Variables tab displays all current values. The Console lets you run Python commands mid-execution.
Took me a while to realize you can drag these tabs around. Customize the layout however works for your workflow.
Most developers keep the Variables tab visible at all times since that’s where the defect tracking really happens.
Step Four: How Do You Inspect Variable Values?
The Threads & Variables tab displays every variable in the current scope with its type and value, updated in real time as you step through code.
Expand objects by clicking the arrow next to them. Nested attributes become visible immediately.
Action
- Threads & Variables tab: Center panel in Debug tool window, shows all local and global variables
- Expand objects: Click arrow icons to reveal nested attributes, lists, dictionaries
- Inline values: Variable values appear directly in the editor next to each line
Purpose
Seeing actual values beats guessing. The inline debugger shows data right where your code lives.
I check variables constantly during error tracing. Usually the bug becomes obvious once you see what the data actually contains.
Step Five: How Do You Step Through Code Line by Line?
Stepping executes your program one line at a time, giving you complete control over execution flow and letting you observe each state change.
Use the stepping toolbar buttons or keyboard shortcuts to move forward through your code.
Action
- Step Over (F8): Executes current line, moves to next line without entering functions
- Step Into (F7): Enters function calls to debug inside them
- Step Into My Code (Alt+Shift+F7): Enters only your code, skips library functions
Purpose
Line-by-line execution reveals exactly where things go wrong.
Without stepping, you’re just guessing. With it, you watch bugs happen in slow motion.
Step Six: How Do You Use Step Over vs Step Into?
Step Over stays in your current function; Step Into follows every function call down the rabbit hole.
Choose based on where you think the bug lives.
Action
- Step Over (F8): Use when the function call works fine, you just need the result
- Step Into (F7): Use when you suspect the bug is inside that function
- Smart Step Into (Shift+F7): Pick which function to enter when multiple calls exist on one line
Purpose
Wrong choice wastes time. Step Over keeps you moving fast when you trust the called code.
Step Into when something in that function smells off. Your gut usually knows.
Step Seven: How Do You Add a Watch Expression?
A watch expression tracks specific variables or calculations across your entire debug session, even as you move between scopes.
Type any valid Python expression and PyCharm evaluates it continuously.
Action
- Watch field: Click “+” in the Variables tab or type in the evaluation field
- Enter expression: Type variable name or calculation like
len(mylist) - Track changes: Value updates automatically as execution progresses
Purpose
Watches save you from scrolling through hundreds of variables.
Pin exactly what matters. I usually watch the variables I suspect are causing trouble.
Step Eight: How Do You Evaluate Expressions During Debugging?
The Evaluate Expression dialog lets you run any Python code using the current program state without modifying your source.
Test fixes before implementing them. Check complex conditions. Call functions manually.
Action
- Open dialog: Press Alt+F8 or right-click and select “Evaluate Expression”
- Enter code: Type any valid Python, from simple variables to method calls
- View result: Result appears immediately, won’t affect actual program state
Purpose
Test hypotheses without restarting. Wonder if sorting that list fixes the issue? Evaluate it and see.
This feature alone makes PyCharm worth using for different types of testing scenarios.
Step Nine: How Do You Resume Program Execution?
Resume Program continues execution until the next breakpoint or program completion.
Use this when you’ve seen enough at the current pause point.
Action
- Resume button: Green arrow icon in the Debug toolbar (left side)
- Keyboard shortcut: F9 on all platforms
- Behavior: Runs until next breakpoint, exception, or program end
Purpose
Jump between breakpoints without stepping through every line. Fast navigation through working code.
Step Ten: How Do You Stop the Debug Session?
The stop button terminates your program and closes the debugger connection.
Your breakpoints stay in place for the next session.
Action
- Stop button: Red square icon in Debug toolbar
- Keyboard shortcut: Ctrl+F2 on Windows/Linux, Cmd+F2 on macOS
- Result: Program terminates, Debug window remains open with last state
Purpose
Clean exit when you’re done or need to restart with code changes.
Verification
After debugging, confirm your fix works:
- Run the program normally (Shift+F10) without breakpoints
- Check that output matches expectations
- Test edge cases that triggered the original bug
- Remove or disable breakpoints you no longer need (Ctrl+Shift+F8 opens breakpoint manager)
Consider adding unit tests for the fixed code to prevent regression issues later.
Troubleshooting
Issue: Breakpoint Not Hit
Solution: Check that you’re running Debug mode (bug icon), not Run mode. Verify your Python interpreter configuration points to the correct environment. Ensure the breakpoint line actually executes in your code path.
Issue: Variables Not Visible
Solution: Click the Threads & Variables tab in the Debug window. If variables show as “not available,” the code hasn’t reached that scope yet. Step forward until variables come into scope.
Issue: Debug Session Does Not Start
Solution: Go to Run > Edit Configurations and verify your script path is correct. Check Settings > Project > Python Interpreter for valid interpreter. Ensure no other debug session is already running.
Issue: Debugger Runs Too Slowly
Solution: Disable “Collect run-time types information” in Settings > Build > Python Debugger. Remove unnecessary breakpoints. Consider using AI debugging tools for complex issues.
Related Processes
Once you master basic debugging, explore these advanced topics:
- Conditional breakpoints: Right-click any breakpoint to add conditions like
x > 100 - Exception breakpoints: Pause automatically when specific exceptions occur (Run > View Breakpoints > Python Exception Breakpoint)
- Remote debugging: Debug code running on servers or containers (PyCharm Professional only)
- Django/Flask debugging: Debug web applications with request-level inspection
The test-driven development approach works well with PyCharm’s debugger. Write failing tests first, then debug until they pass.
For larger projects, combine debugging with proper source control practices. Track which commits introduced bugs using Git integration.
PyCharm’s debugger integrates with the broader software development process. Use it alongside code review to catch issues before they reach production.
FAQ on How To Debug In PyCharm
What Is the Keyboard Shortcut to Start Debugging in PyCharm?
Press Shift+F9 on Windows/Linux to start a debug session. Mac users press Ctrl+D.
This launches your script with the debugger attached, enabling breakpoint suspension and variable inspection throughout code execution.
How Do I Set a Conditional Breakpoint in PyCharm?
Right-click any existing breakpoint (red dot) and select “More” or press Ctrl+Shift+F8.
Enter a Python condition like x > 100. The debugger only pauses when that condition evaluates to True.
What Is the Difference Between Step Over and Step Into?
Step Over (F8) executes the current line and moves to the next without entering function calls.
Step Into (F7) follows function calls to debug inside them. Use Step Over when you trust the called code.
How Do I View All Breakpoints in PyCharm?
Press Ctrl+Shift+F8 to open the Breakpoints dialog. This displays every breakpoint in your project.
You can enable, disable, add conditions, or remove breakpoints from this centralized manager.
Can I Debug Django or Flask Applications in PyCharm?
Yes. PyCharm Professional supports Django and Flask debugging with request-level inspection.
Create a Django/Flask run configuration, set breakpoints in your views, and start debugging. The debugger catches requests as they hit your code.
How Do I Evaluate Expressions While Debugging?
Press Alt+F8 during a paused debug session to open the Evaluate Expression dialog.
Type any Python code to test hypotheses without modifying your source. Results appear instantly using the current program state.
Why Is My Breakpoint Not Being Hit?
Common causes: running in Run mode instead of Debug mode, incorrect Python version configuration, or the breakpoint line never executes in your code path.
Verify you clicked the bug icon, not the green play button.
How Do I Debug Remote Python Scripts in PyCharm?
PyCharm Professional supports remote debugging via SSH or Docker.
Configure a remote interpreter in Settings > Project > Python Interpreter, then create a remote debug configuration. Community Edition lacks this feature.
What Is Inline Debugging in PyCharm?
The inline debugger displays variable values directly in the editor next to each line of code.
No need to check the Variables tab constantly. Values update automatically as you step through your program.
How Do I Debug Unit Tests in PyCharm?
Right-click any test file or function and select “Debug” instead of “Run.”
Set breakpoints inside your test code or the functions being tested. PyCharm’s debugger works seamlessly with pytest, unittest, and other integration testing frameworks.
Conclusion
Learning how to debug in PyCharm transforms your approach to fixing Python code. No more scattered print statements or blind guessing.
You now have the skills to set breakpoints, step through code, and inspect variables at any execution point.
The stepping controls (Step Over, Step Into, Step Out) give you precise navigation through your program’s call stack. Watch expressions and the Evaluate Expression dialog let you test fixes before changing source files.
Conditional breakpoints save hours on complex bugs. Exception breakpoints catch errors the moment they occur.
Start with simple scripts. Build confidence with the debug toolbar. Soon you’ll debug Django apps, Flask APIs, and multi-threaded programs without breaking a sweat.
PyCharm’s debugger becomes second nature with practice.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, and Speckyboy, and Slider Revolution among others.
- Agile vs DevOps: How They Work Together - March 11, 2026
- Ranking The Best Mapping Software by Features - March 11, 2026
- Waterfall vs Spiral Model: Pros and Cons - March 10, 2026
