Skip to main content

Distribute a geoprocessing module

Distribute and install a custom geoprocessing module by following standard patterns of distributing Python packages.

This topic follows the foo module example from the Create geoprocessing modules topic.

Distribute a geoprocessing module as a compressed archive

To distribute a geoprocessing module as a compressed archive, archive the module (the foo package, as an example) as a .zip file or other preferred compression format. Then provide the following steps to your audience:

  1. Clone the default ArcGIS Pro conda environment.

    Note:

    Modifying the ArcGIS Pro default Python environment (arcgispro-py3) is not advisable and may result in unintended consequences. It is recommended that you only modify a cloned environment.

  2. Extract the foo package into the clone's site-packages folder (%LocalAppData%\ESRI\conda\envs\<clone_environment_name>\Lib\site-packages).

  3. Switch the current ArcGIS Pro conda environment to the cloned environment using the Python Package Manager.

Distribute a geoprocessing module with pip

Geoprocessing modules can be distributed through pip with a wheel file by using the setuptools library.

Note:

To distribute a module with pip, the conda, pip, setuptools, and wheel packages are required in your Python environment. These packages are included with the default ArcGIS Pro Python environment.

Create a wheel file for distribution

A distribution package is required for the foo package so that it can be installed in the Python site-packages directory. With a distribution package, the package can be shared and used by others.

To create a wheel file, complete the following steps:

  1. Create a setup.py script similar to the following:

    setup.py

    Sample code to create a setup.py script.

    import os
from setuptools import setup

def read(fname):
    return open(os.path.join(os.path.dirname(__file__), fname)).read()

setup(name='foo',
      version='1.0',
      author='Esri',
      description=("Example for extending geoprocessing through Python modules"),
      long_description=read('Readme.txt'),
      python_requires='~=3.3',
      packages=['foo'],
      package_data={'foo':['esri/toolboxes/*',
                  'esri/arcpy/*', 'esri/help/gp/*',
                  'esri/help/gp/toolboxes/*', 'esri/help/gp/messages/*']
                  },
      )

  2. If distributing a geoprocessing module that supports additional languages, the setup function's package_data parameter must include the additional language directories. For example, if including a Spanish localization, setup.py should be the following:

    setup.py for Spanish localization

    Sample code for setup.py to include Spanish localization directories.

    import os
from setuptools import setup

def read(fname):
    return open(os.path.join(os.path.dirname(__file__), fname)).read()

setup(name='foo',
      version='1.0',
      author='Esri',
      description=("Example for extending geoprocessing through Python modules"),
      long_description=read('Readme.txt'),
      python_requires='~=3.3',
      packages=['foo'],
      package_data={'foo':['esri/toolboxes/*',
                  'esri/arcpy/*', 'esri/help/gp/*',
                  'esri/help/gp/toolboxes/*', 'esri/help/gp/messages/*',
                  'esri/help/es/gp/*', 'esri/help/es/gp/toolboxes/*',
                  'esri/help/es/gp/messages/*']
                  },
      )

    The setup.py build script sets several properties and directs the build utility to the package directory. The long description is stored in an accompanying Readme.txt file. The setup.py and Readme.txt files should be located in the src directory. For more information on using setup(), see Packaging and distributing projects. The directory structure for the foo package will be as follows (exclude the additional es Spanish language folder if only supporting English):

    Src
├  setup.py
├  Readme.txt
└──foo
    ├  __init__.py
    ├  bar.py
    └──esri
        ├──arcpy
        │   └  SamplePythonToolbox.py
        ├──help
        │   ├──es
        │   │   └──gp
        │   │       ├  SamplePythonToolbox_toolbox.xml
        │   │       ├  SampleTool_SamplePythonToolbox.xml
        │   │       ├──messages
        │   │       │   └  messages.xml
        │   │       └──toolboxes
        │   │           └  SamplePythonToolbox.xml
        │   └──gp
        │       ├  SamplePythonToolbox_toolbox.xml
        │       ├  SampleTool_SamplePythonToolbox.xml
        │       ├──messages
        │       │   └  messages.xml
        │       └──toolboxes
        │           └  SamplePythonToolbox.xml
        └──toolboxes
            ├  SamplePythonToolbox.pyt
            ├  SamplePythonToolbox.pyt.xml
            └  SamplePythonToolbox.SampleTool.pyt.xml

  3. To build an installer for the foo package, run the following command from the src directory using the command prompt:

    python setup.py sdist bdist_wheel

    The sdist bdist_wheel command creates dist, build, and foo.egg-info folders in the src parent directory. In the dist folder, a wheel file named foo-1.0-py3-none-any.whl is created. A wheel file can be distributed directly with pip.

Install from a wheel file using pip

After cloning and switching environments, open the Python Command Prompt to install the wheel file directly with pip. Pip will install the wheel file in the active environment.

  1. Run the following command from the Python Command Prompt from the src\dist directory:

    pip install foo-1.0-py3-none-any.whl

    When the foo package is installed, the following directory structure will be created in the site-packages directory (exclude the additional es Spanish language folder if only supporting English):

    site-packages
└──foo
    ├  __init__.py
    ├  bar.py
    └──esri
        ├──arcpy
        │   └  SamplePythonToolbox.py
        ├──help
        │   ├──es
        │   │   └──gp
        │   │       ├  SamplePythonToolbox_toolbox.xml
        │   │       ├  SampleTool_SamplePythonToolbox.xml
        │   │       ├──messages
        │   │       │   └  messages.xml
        │   │       └──toolboxes
        │   │           └  SamplePythonToolbox.xml
        │   └──gp
        │       ├  SamplePythonToolbox_toolbox.xml
        │       ├  SampleTool_SamplePythonToolbox.xml
        │       ├──messages
        │       └──toolboxes
        │           └  SamplePythonToolbox.xml
        └──toolboxes
            ├  SamplePythonToolbox.pyt
            ├  SamplePythonToolbox.pyt.xml
            └  SamplePythonToolbox.SampleTool.pyt.xml
    Note:

    The messages folder is only present if there are message files in the package.

  2. If your computer has restrictions that prohibit running an installation, copying the foo directory from the build\lib directory to the %LocalAppData%\ESRI\conda\envs\<environment_name>\Lib\site-packages folder will produce the same effect as installing from an archived file. When copying the package manually, it will not be recognized or managed by pip.

Use the geoprocessing module

In ArcGIS Pro, the SamplePythonToolbox tool is available from the Geoprocessing pane and is searchable. The toolbox and tool can also be accessed from arcpy as follows: arcpy.SamplePythonToolbox.SampleTool()

Using ArcGIS Pro and the Python package development process, it is possible to build and distribute a package that extends geoprocessing with custom toolboxes that can be viewed and run from within the ArcGIS system toolboxes and arcpy, and the geoprocessing module can be internationalized to support multiple languages.