Creating a new Python toolbox in ArcGIS

by | October 22, 2016

Hey guys, so here is a brief introduction to creating a simple Python toolbox in ArcGIS. Python toolboxes are extremely useful as they can be shared between members in a team or online, and work like a normal tool within ArcGIS. You can perform many of the same tasks with a Python script tool, however the main drawback is the lack of extensibility and less optimal workflow when sharing the tool.

I anticipate you have at least a cursory understanding of core concepts in Python programming and scripting. You must at least understand the definitions of the following and how they relate to Python:

  • variable
  • parameter
  • function
  • class
  • inheritance
  • boolean
  • list
  • dictionary
  • tuple

What you will need to follow along.

I am using ArcGIS 10.2.2 Desktop for this tutorial, however it will be much the same in any version from 10.1 – 10.4 and within ArcGIS Pro.

Remember, ArcGIS Pro uses Python 3.4 which may mean that the code you see me write here may not work without modification on ArcGIS Pro. 

Some sort of Python editor. ArcGIS comes packaged with Idle which I don’t like and Esri often recommends PyWin. Personally I use PyCharm as it allows for a much more effective Python development workflow in my opinion but everyone has their own preference. If my screenshots look different from your’s that’s just fine.

Creating your toolbox.

There are two ways to create a toolbox in ArcGIS, the first is through the catalog in ArcMap or ArcCatalog and the other is directly in your script editor of choice. For beginners I recommend going through the catalog in ArcMap as that way a lot of the boilerplate code is injected and you can move right on to customizing the tools.

Creating a new toolbox in ArcMap.

First, open an existing or new blank map in ArcMap and expand the Catalog pane.

Catalog Pane

You can create a Toolbox anywhere, but I tend to create them in my Python IDE project folder. To create a new toolbox right click the folder you wish to place it in and select “New > Python Toolbox”New Python Toolbox


All Python toolboxes end with the file extension “.pyt” so make sure to include that in your filename when you name it.

This process creates a set of files within that folder: name.pyt, name.pyt.xml and name.Tool.pyt.xml. When we edit the tool, we just need to concern ourselves with the name.pyt file.

You can right click the toolbox and click “edit” to launch your default python script editor. Notepad works just fine, but like I said a more full-featured one is always better.

Once your text editor is open, you will see some code has already been generated:

New toolbox code sample

Inside you see two class code blocks with some functions defined within. The first class is the “Toolbox” class and this class contains all the information ArcMap needs to determine what is inside the toolbox.

The second class is a default “Tool” class. This is the basic outline required to make a tool run within the arcpy geoprocessing framework.

Let’s start at the top with the Toolbox class.

As you can see in the image above the toolbox class is defined and inherits the “object” class. We then initiate the class with the following variables:

self.label = "Toolbox"
self.alias = "" = [Tool]

You can see the self.alias variable is defined as an empty string and the variable is defined as a list with a single object in it. If you want to change the tool’s alias under its properties in ArcCatalog you can enter a new one into the string variable self.alias.

Adding a new tool to the toolbox.

If you want to add another tool to your new toolbox, copy the entire Tool() class and paste it below. Make sure you rename the second Tool() class to something different. Tool2() is fine, but a more descriptive class name is always better.

Go back up to the Toolbox() class and add the new tool as another object in the list. = [Tool, Tool2]

Refresh your catalog pane and you will see that there are now two tools in the toolbox.

Editing your tools.

Much like the Toolbox class, you will see a function:

def __init__(self):
    """Define the tool (tool name is the name of the class)."""
    self.label = "Tool"
    self.description = ""
    self.canRunInBackground = False

You may choose to give your tool a new label, add a description and define whether or not it should be allowed to run in the background.

Take a look through the rest of the functions in the class and try to determine what they each represent. In my next post I will go over adding parameters to the tool, adding the code to be executed and testing your tools.

2 thoughts on “Creating a new Python toolbox in ArcGIS

  1. Laura Day


    I am creating a python toolbox and want to use PyCharm. I am currently having the issue where pyCharm isnt recognizing the extension .pyt. How did you add the file type to pycharm to be able to work on your script? Hopefully you can help.

    1. Ed

      Here’s a > 2 year response to Laura’s question, but here it goes in case anyone else has the same question. lol

      In Pycharm Community version 2020.1 you can add other file types to be recognized as Python files as follows:

      – File -> Settings -> Editor -> File Types
      – Scroll down pass all the recognized file types to Python. Clicking it will show you registered patterns recognized as Python.
      – Click the plus symbol to add a new pattern and type *.pyt
      – Hit apply and ok.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.