Why learn/use Python Toolboxes over Python Script Tools?

The two are very, very close in functionality but not completely equivalent.

Common to both

  • Includes a set of tools with a unique alias for identification
  • Can call from arcpy
  • Get a Geoprocessing tool dialog (essentially a full UI) for free for each tool
  • Can keep all Python code in one file (embedding tool source in TBX, holding all the implementation in one PYT) and distribute via email or shared network drives
  • Always run in foreground setting for desktop applications. Setting "Always run in foreground" within ArcPy code?

Unique to TBX files:

  • Can include references to system toolboxes, custom COM tools, and custom .Net tools
  • Model Builder tools can be included in the toolbox
  • Tool documentation is stored inside the .tbx file
  • Easy wizard UI for setting up parameters and doing validation code
  • Run Python Script in Process tool property
  • Disadvantage: Opaque binary format, newer versions of TBX files need to be explicitly saved as older versions to work in previous versions of the software, the UI can be a double edged sword as you have to switch between property pages to see if you missed a setting (such as relative paths)

Unique to Python Toolboxes:

  • Plain text, so toolboxes can be treated the same as any other code (useful in environments where good revision control tooling is used as you can trace its development history -- look at how many projects on GitHub use PYT over TBX.)
  • Have more control over certain parameter types (namely you can do composite datatypes and define value tables' schemata)
  • isLicensed property can be used to disable a tool if a product ("ArcInfo") or extension ("spatial") is not available.
  • Tool documentation is stored in XML files in same folder as the .pyt
  • Disadvantage: No wizard UI for configuring tool parameters, significantly more scaffolding code in Python, turns Toolbox development into more of a formal software development task over simply adding an implementation script. Reloading a pyt to load changes while developing can be slow if pyt is large (this can be avoided by putting tools in other files and importing so they don't need to be re-compiled).

A while ago when I was working on my first dozen or so PYT toolboxes I got flustered at how much of a hassle it was to set up a PYT for the first time, so I developed a tool called tbx2pyt. It'll take a TBX toolbox and convert it to a PYT with a minimal loss of code. In fact, the PYT that powers it was first a TBX. This may be a good way to transition existing tools to the Python Toolbox format if you so desire. At the very least, it makes it possible to set up your tools' parameters using the UI before switching to code.


The help section titled Comparing custom and Python toolboxes has a pretty good comparison of why you might choose one over the other, although I'd be curious to hear "real world" advantages/disadvantages from those experienced in creating Python Toolboxes.

One clear disadvantage that I read is the inability to mix/match models & scripts in a Python Toolbox, as you can in a standard Custom Toolbox.


My number one reason for leaning towards python toolboxes is for version control and source code management (see Applying version control to ArcGIS Models), followed very closely by being able to use a code editor/IDE with tab completion, regular expressions, snippet libraries, etc.

However as Ryan Dalton notes, by doing so you lose the ability to use Model Builder and old style Tools -- unless you're willing to go through the effort of building the model as per usual and then exporting to python and then rewriting to fit into the .pyt. (If you do this take a look at Guidelines for organizing Python Toolboxes (.pyt) in ArcGIS). At present this disadvantage is big enough that I've yet embark on using python toolboxes seriously.

If you have existing toolboxes you'd like to convert to .pyt, you may find Jason Scheirer's tbxtopyt partial converter useful.

As for the "compelling case?" part of the question: if you already have some software development chops, yes definitely. If like me you're 3 parts GIS Tech/Analyst and 1 part or less pythonista, not so much. (At least not yet -- I really hope this binary one or the other nature of the two approach changes in a near future release.)