Debug script tools with Microsoft Visual Studio

To debug script tools in Microsoft Visual Studio, the Visual Studio Python development workload must be installed.

See Modify Visual Studio workloads, components, and language packs on the Microsoft Learn site for more information.

Debug Python code in ArcGIS Pro

To start debugging Python code in ArcGIS Pro, complete the following steps:

1. In ArcGIS Pro, open the tool to be debugged in the Geoprocessing pane.
2. Start Microsoft Visual Studio, and open the script to be debugged.

   For script tools (.atbx file), some additional setup may be required to debug execution code.

3. On the Microsoft Visual Studio main menu, click Debug > Attach to Process.
4. On the Attach to Process dialog box, click the Select button.
5. On the Select Code Type dialog box, check Debug these code types, check Python, and click OK.

   You must choose Attach to: Python code. Do not use the default code type of Automatic: Managed (v4.6, v4.5, v4.0) code, Python code.

6. In the list of available processes, click the ArcGISPro.exe process, and click the Attach button.
7. Place breakpoints as needed.
8. Run the tool in ArcGIS Pro to start debugging.

After detaching the integrated development environment (IDE) from ArcGIS Pro, exceptions in the Python code will not display correctly. To address this, restart ArcGIS Pro.

To learn more about debugging Python code in Visual Studio, see Debug your Python code in Visual Studio on the Microsoft Learn site.

Note:

Microsoft Visual Studio 2019 and later use a Python debugger based on debugpy, which is supported natively by ArcGIS Pro without any additional setup.

Debug script tool execution code

When the script tool's execution code is embedded, you must first export the script from the toolbox before you can debug it.

To debug the script tool's execution code, complete the following steps:

1. Open the script tool properties dialog box, and click the Execution tab.
2. If the execution script is embedded, click the Export script to file button.
3. Continue with the exported .py file.

Debug script tool validation code

When Python code in the script tool validation is embedded in the tool, you must first copy the code to an external Python file (.py) to debug it. You can then open the Python file in your IDE and set breakpoints, attach the IDE to ArcGIS Pro, and run the script tool. Upon completion of the code modification, copy the contents of the Python file back into the tool validation.

To debug script tool validation code, complete the following steps:

1. Open the script tool properties dialog box, and click the Validation tab.
2. Copy the code into a .py file (validate_code.py in this example).
3. Replace the code on the Validation tab with the following sample code:

In the following example, validate_code.py (contents not shown) contains the ToolValidator class and is saved to the same directory as the toolbox. Place the following code snippet into the code editor of the tool properties dialog box Validation tab to relay debugging to validate_code.py.

import os
import sys

sys.path.append(os.getcwd())  # Ensure directory containing module is in Python path
import validation_code

# The following code will reload the val.py module if it's modified
if 'validation_code' in sys.modules:
    import importlib
    importlib.reload(validation_code)

# ToolValidator should exist at the global scope
ToolValidator = validation_code.ToolValidator

4. Continue debugging with the validate_code.py file.
5. When you are done debugging, replace the contents of the code editor on the tool properties dialog box Validation tab with those of the .py file (validate_code.py in the sample code).

The validation code in script tool validation is run repeatedly as a user interacts with a tool.