Debugging Python in ArcGIS Desktop

Published on December 27, 2018

Sometimes it’s just useful to debug ESRI script tools rather than peppering them with arcpy.AddMessage() commands – try looping through a dictionary object that way.

We haven’t yet moved to ArcGIS Pro so forgive me if I’ve yet to see the light but for those still working with ArcGIS Desktop here are some steps to follow to use Python’s stock pdb debugger from a stock install of ArcGIS 10.4.1. No additional components required.

Script tools are by their very purpose configured to work within the geoprocessing environment, by geoprocessing I mean run in ArcCatalog or ArcMap rather than as a stand-alone script.

To this extent they usually have parameters which are completed via a nifty form such as this one:

Subsequent to that the script-tool will include a section of the form that contains code where all of these parameters are processed:

all of those parameters would need to be captured and added manually in the case of attempting to run the script as a stand-alone script for the purposes of debugging. That’s not fun, requiring you to add a bunch of print statements – or arcpy.GetMessages() statements – if running as a script tool, then manually setting each variable to the output provided, then running the script manually. Then making changes. Then setting it all back to how it was. Then discovering it doesn’t work. And repeat ad infinitum; ad nauseum.

In place debugging is useful to avoid all this. ESRI don’t offer a huge amount if insight into how this works. The most recent web-post being something for ArcGIS Pro. Google for ‘Debug Python Code “esri”’ it brought me here. Not exactly a step by step guide I thought…

I ended up following the pdb Module approach. Here is a step by step guide for my own personal notes (and anyone else who might find it useful).

I decided to use the pdb module as it’s already installed with the stock installation of Python. I believe this is the case with all versions of ArcGIS using Python (caveat – I’m using 10.4.1). To check open the ESRI python install command prompt and import the pdb module:

Read the pdb docs for more information on using pdb.

Ensure the Editor and Debugger are set in the Geoprocessing Options. I’m using IDLE as it comes with the Python install

Right click on the script-tool you wish to debug

This should open the script tool to include all necessary parameters as before but this time when it’s opened the Python associated with it will also open and the tool will appear to hang.

Include a break point within the script where required.

Run the code from within the IDLE environment (Run, Run Module) which should stop at the break point set. Note. It make ask to save your source – you will need to.

Do Debugging


Navigate through the code using the pdb commands as described in the docs.

When done close the debugger.

Remove reference pdb import and pdb breakpoint from the script, for what should be obvious reasons (otherwise when next running the script tool the break point will kick and halt the progress of the script-tool).

You should be left with the script-tool dialogue box with however many minutes of debugging time was spent.


Note the script-tool will only complete as far as is progress was made during debugging. When the IDLE windows are closed the script stops.


Additional comments have been disabled for this entry

An entry posted on December 27, 2018.

Categories: GIS and Python

Tags: arcmap , esri and python