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 AllSource

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

1. In ArcGIS AllSource, 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), some additional setup may be required to debug execution code. Additional setup is also required for debugging Python toolboxes (.pyt). Refer to the sections below for details.

3. Insert the arcpy.SetupDebugger() function at the top of the script you are debugging, after any imports.
4. On the Microsoft Visual Studio main menu, click Debug > Attach to Process.
5. On the Attach to Process dialog box, click the Select button.
6. 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.

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

After completing debugging, remove any arcpy.SetupDebugger() calls from the code if necessary.

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

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 2017 can be used to debug ArcGIS AllSource 2.1 and later. Earlier versions of either of these applications are not supported. Microsoft Visual Studio 2022 and later use a different Python debugger, and debugging ArcGIS AllSource Python scripts requires the inclusion of the arcpy.SetupDebugger() function.

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. Add an arcpy.SetupDebugger() call after the imports.
4. 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 AllSource, 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. In the .py file, add an arcpy.SetupDebugger() call after the imports.
4. 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
import validation_code

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

# 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

5. Continue debugging with the validate_code.py file.
6. 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), and remove arcpy.SetupDebugger().

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

Debug Python toolboxes

You cannot debug a Python toolbox (.pyt) directly; instead, it must be debugged using a .py file.

To debug a Python toolbox, complete the following steps:

1. Create an external .py file (execute_code.py in this example) in the same directory as the Python toolbox.
2. Copy the code in the execute function of the Python toolbox to a function (func) in the new Python file, and copy over any other necessary functions.

The following is an example of the contents of execute_code.py, which is saved to the same directory as a .pyt file.

import arcpy

def func(parameters):
    arcpy.AddMessage("This is where your code goes.")
    return

3. Replace the code in the Python toolbox execute method with the following:

The following is an example of the modified execute function in a Python toolbox.

arcpy.SetupDebugger()
import execute_code
execute_code.func(parameters)

4. Continue debugging using the execute_code.py file.
5. When you are done debugging, copy the contents of func from the Python file (execute_code.py in the sample) back to the tool's execute function.