Tip: Python Addins - getting custom tools/toolbox to work - GPToolDialog error and other tips (9/7/2017)

Discussion created by rastrauch Champion on May 15, 2013
Latest reply on May 10, 2019 by cwholmes

This is an older post, but using it for a place to store my Python addin gotchas and fixes.  The date in title is last update.

NOTE: Python Addins will not work with Pro, however the Tools in your Toolbox may, although may need some tweaking


9/7/2017 - note... the {..} folders are stored in C:\Users\<user>\AppData\Local\ESRI\<Desktop10.x>\AssemblyCache\ 

this is typically a hidden path and may require admin rights to access.  Making note of this as I move to 10.5.x and may need to manually move the folders is the .addin doesn't work. Sometimes will not even on different versions.  Sharing and installing add-ins—Help | ArcGIS Desktop 


Error message: The "TypeError: GPToolDialog() takes at most 1 argument (2 given)" is a very misleading message and is a bug (NIM089253)
   My solution:

  • This process helped me get rid of this message and was a simple was to add my custom python tool/toolbox to an addin button. [Update/comment...actually I think the error message still shows in the Python window, but it seems to be harmless]
    • This post assumes you have already run the wizard so some buttons are stubbed out and you are modifying the addin_addin.py (or YourProjectName_addin.py if you renamed it).  I'm assuming it will work with other classes, but I only tested it with toolbar-buttons.
    • This also let me take advantage of the python tools that I already had working in my toolbox. One of the advantages of this is that any dialog box you already have associated with your tool on start-up (i.e. in the tools parameter tab) will still be in place.
  • Some of this info is scattered around the forums (but the online help is lacking right now), so I thought it may help to consolidate what worked for me, in case it helps others.  This is how I was able to get the GPToolDialog to work with my custom python tools/toolbox:
    • Copy your .tbx file into the addin wizards "Install" folder.
    • Create a "scripts" folder in the same location
    • Copy all your .py script to this folder
    • Open the .tbx in the Install folder, make sure "relative path" is checked, and re-point all the tools to the new script location
    • the "import os" and the "relPath = " line seem to be the key....see sample code below


import arcpy
import pythonaddins
import os
relPath = os.path.dirname(__file__)
toolPath = relPath + r"\CheckAndFixLinks.tbx"

class ButtonClass1(object):
  """Implementation for YourProjectName_addin.button (Button)"""    
  def __init__(self):       
    self.enabled = True       
    self.checked = False    
  def onClick(self):       
    """ tool path could also be set here instead, if you would like   """     
    pythonaddins.GPToolDialog(toolPath, "ToolNameFromToolbox")

Updated 10/18/2015: modified lines 5 and 13 to remove some confusing info.


TIP: If you have any custom or special python modules you want to package with the addin, that is modules that are usually stored in C:\Python27\ArcGIS10.1\Lib (which you may import in your tools) but aren't part of the normal ArcGIS or Python install, if you place these in the scripts folder, that seems to work the best.


TIP/Warning: Remember, if you open the project up in the wizard again....which is sometimes necessary...and it tells you it is saving a backup _addin.py file, this backup contains the customization you did and the new file may be back to the defaults from the wizard.  You may need to open both files and copy any custom code back into the new file.


This method seems to be the cleanest process I've found to do this, at least at version 10.1 (and the addin released April 2012).


Anyone else have tips?


Tip - missing button images (added 8/1/2017) - I've had addin's that were working fine and had the button images, then updated the button layout or other item in the config, and then received an error that the images were missing (when I know they are not).  This is a bit misleading, but chances are I messed up when I modified one (or more) of the following: the Toolbox, the config.xml or the <name>_addin.py file. What I check to get it to work:

  • In the toolbox:
    • Check to make sure the path to the .py associated with a Tool, is correct (in the Tool's property)
  • Config.xml
    • for any syntax errors of missing   < or >  etc.
    • Make sure the that every <Commands><Button ...  id="name.button">  has a matching <Toolbars><Toolbar..><Items><Button refID="name.button">   They must match,  and it is helpful to read if int he same order. 
    • Check for typos
  • <addin name>_addin.py
    • check for any syntax error
    • make sure that every <Commands><Button ...  class="classname">  in the config.xml file has a matching "class <classname>(object):  in the file
    • check for typos


Tip -  "Different versions" (added 6/14/2016) - ran into this issue today Add-In Wizard unable to find matching ArcGIS installation on this machine because I have different ArcGIS versions on different machines.  Leaving the version at 10.2.2 allowed me to install on both 10.2.2 and 10.3 machines.  My additional comments on this thread.... https://community.esri.com/message/615036#comment-615036


Tip:  (added 6/16/2016) Having issues with getting the .addin to actually install or update in ArcCatalog/Map??  OR, updating often and don't want to have to close/reopen after updating?

In the ArcCatalog/Map (whichever the addin was created for),   Customize->Toolbars->Customize->Add-From-File  navigating to the location of the <addin>.esriaddin file and select that file.  After the normal confirmation page to "Install Add-In",  another window popped up that showed it adding the tools in my addin toolbox

To verify it worked, you can check to see if the update date has changed for the addin, you can go to the

C:\Users\<username>\AppData\Local\ESRI\<Desktop version>\AssemblyCache

folder.  You may need to 1) give windows explorer permission for you to view this folder, and 2) go into the {hashtag} folders to see which is the correct addin folder.

Not having to close and reopen my Catalog/Map session to get this to update is really a time saver!

-->Note (added August 3, 2016) - this method will only work if updating the .py file.  If the actual toolbox

  or tool are updated, still need to close/double-click-addin-file/open to have it appear.


Latest help docs:

What is a Python add-in?—Help | ArcGIS for Desktop 10.3.x

What is a Python add-in?—Help | ArcGIS for Desktop 10.4.x


tagging my own blog so I can find this again hopefully:  Rebecca's GIS in Alaska

Python AddIns python snippets