How to Debug Python Scripts in FreeCAD

Debugging Python scripts inside the FreeCAD environment can be accomplished through several methods depending on your workflow complexity. This guide covers the primary techniques to inspect and troubleshoot your code, ranging from lightweight built-in tools like the FreeCAD Python console and Report View to professional remote debugging setups using external editors such as Visual Studio Code and PyCharm.

Using the Built-In Console and Report View

For quick inspection and minor troubleshooting, FreeCAD provides native output tools that do not require external configuration.

Enable the Python Console and Report View: In FreeCAD, navigate to View > Panels and ensure both Python console and Report view are checked.
Standard Output and Errors: Standard print() statements are directed to the Report View.

FreeCAD Logging Methods: For structured logging, use the native FreeCAD.Console methods:

import FreeCAD

FreeCAD.Console.PrintMessage("Standard message\n")
FreeCAD.Console.PrintWarning("Warning message\n")
FreeCAD.Console.PrintError("Error message\n")

Live Object Inspection: The Python console shares the live FreeCAD runtime state. You can interactively inspect geometry, document objects, and variables after running a script.

Remote Debugging with Visual Studio Code

Attaching Visual Studio Code via debugpy is the most robust way to set breakpoints, inspect variables, and step through code execution line by line.

1. Install debugpy

Install debugpy into the specific Python environment used by your FreeCAD installation. Open your system terminal or command prompt:

Windows (FreeCAD bundled Python):

"C:\Program Files\FreeCAD 0.21\bin\python.exe" -m pip install debugpy

Linux / macOS:
```
python3 -m pip install debugpy
```

2. Configure VS Code

Create a debug configuration in your project's .vscode/launch.json file:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Attach to FreeCAD",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "${workspaceFolder}"
                }
            ]
        }
    ]
}

3. Add Connection Code to Your Script

Insert the following snippet at the beginning of the macro or workbench script you want to debug:

import debugpy

# Allow FreeCAD to listen for the VS Code debugger
debugpy.listen(("localhost", 5678))
print("Waiting for VS Code debugger to attach...")
debugpy.wait_for_client()  # Pauses execution until VS Code connects
debugpy.breakpoint()       # Optional: breaks immediately at this line

4. Execute the Debugger

Run the script inside FreeCAD (via the Macro dialog or Python console). FreeCAD will pause at debugpy.wait_for_client().
In VS Code, go to the Run and Debug view and select Python: Attach to FreeCAD.
Press F5. Execution will halt at your breakpoints, allowing full inspection.

Remote Debugging with PyCharm Professional

PyCharm Professional supports remote debugging using the Python Debug Server.

Create a Run Configuration: In PyCharm, create a new run configuration using the Python Debug Server template. Set the port to 12345.
Install pydevd-pycharm: Run pip install pydevd-pycharm~=<PyCharm_Version> inside FreeCAD's Python environment.
Start the Server: Start the debug server in PyCharm.

Add the Trace Hook in FreeCAD:

import pydevd_pycharm

pydevd_pycharm.settrace('localhost', port=12345, stdoutToServer=True, stderrToServer=True)

Run the script in FreeCAD. PyCharm will catch the execution trace automatically.

Command-Line Debugging with `pdb`

If you launch FreeCAD directly from a terminal, you can use the standard Python debugger:

Launch FreeCAD from your terminal:
```
freecad
```
Insert a breakpoint directly in your script:
```
import pdb; pdb.set_trace()
```
Run the script inside FreeCAD. The FreeCAD graphical interface will pause, and the interactive (Pdb) prompt will appear in the terminal window from which FreeCAD was started.