How to Debug Python Toolboxes in 3 Easy Steps

This blog demonstrates how you can debug a Python Toolbox (.pyt) to troubleshoot and fix any errors that may be causing your tool to fail or produce invalid results.

Python Toolboxes are new at ArcGIS 10.1 and provide a new way to create geoprocessing tools entirely in Python with no requirement to use ArcGIS for Desktop.

The following screen capture illustrates three things you must do to start debugging your Python Toolbox. For clarity, some methods have been collapsed and documentation strings are removed.

  1.  Add a main() function. Within this function, create an instance of the tool class and call it’s execute() method. The arguments for execute() include the parameter information created by the getParameterInfo() method and the messages which are set to None.
  2. Comment out existing lines for retrieving parameter values, and enter hard-coded parameter values.
  3. Set a break point at the position where you want to start stepping through the code.

That’s it!  In three simple steps, you can begin debugging and troubleshooting any problems with your Python Toolbox. After the problems are fixed, remove the parameter values you entered, as well as, the main() function.


A Python Toolbox is an ASCII-based file with a .pyt extension. By default, Python IDE’s do not recognize this extension as a Python file type. Fortunately, most IDE’s have an option where you can change the syntax to Python. Here are the steps to do this in PyScripter and Wing IDE.

PyScripter – Go to the View menu, Syntax and select Python.

Wing IDE – Go to the Source menu, Current File Properties… and select the File Type to be Python.

This entry was posted in Python and tagged , . Bookmark the permalink.

Leave a Reply


  1. Curtis Price says:

    Right on, Jason! Thanks for posting this critically needed info!

  2. g3martin says:

    Good times.

  3. g3martin says:

    Any tips on debugging updateParameters()?

  4. paulbrandt73 says:

    I discovered another way of getting PyScripter to recognize the .pyt files more permanently. Under Tools|Options|IDEOptions add the following in the File Filters section:
    “File explorer filter” add “;*.pyt”
    “Open dialog Python filter” add “;*.pyt” inside the parentheses and at the end.

  5. jjrogers says:

    One more hint. This works from the IDE not from ArcCatalog. I spent hours trying to make the debug option in ArcCatalog work with this until an ESRI support person enlightened me.

  6. martinhvidberg says:

    That is a very useful trick – I have been looking for that !

    Unfortunately I have a script that includes:
    mxd = arcpy.mapping.MapDocument(‘CURRENT’)
    and then is picking data from the TOC to work on.
    The tool should obey Definition queries as well as Selections, so it’s not really an option to test run it ‘outside’ ArcMap.

    I have tried all I can think of, but I still can’t make the .pyt update in the toolbox, other ways than by restarting ArcMap – which is very inconvenient when developing/debugging a .pyt-based tool.

    Any good suggestion on how to develop/debug a tool in a .pyt, and have the tool inside the ArcMap toolbox update your latest edits, without having to restart ArcMap?

    Best regards

  7. valraa says:

    Great post! After 5 years I am still finding it very useful. Denugging is tremendously important when coding. Only one thing to note: in the main() function call, “tbx = Toolbox()” is not necessary.