Introduction to arcpy.mp

Arcpy.mp is a Python submodule that is part of the ArcPy site package. It is installed with ArcGIS Pro and is available to all licenses. It was designed primarily to manipulate the contents of existing projects (.aprx) and layer files (.lyrx). You can automate the contents of projects without even having to open the application. In some cases it provides capabilities that are not available to ArcGIS Pro, for example, arcpy.mp is required to build complete map books because it includes functions to export to, create, and manage PDF documents.

It is easier to understand the capabilities of arcpy.mp by describing some scenarios it facilitates. The following are some of the many workflows that an arcpy.mp Python script can help you accomplish:

  • Automate exporting Layouts, Map Views, Map Series and Reports
  • Build a variety of PDF map books, for example, a reference map book or a thematic map book with title page, multiple map pages, and any number of additional pages with supporting content, such as tabular reports and contact lists.
  • Manipulate elements on a layout such as updating a picture, a company logo, or update text strings and so much more.
  • Extend geoprocessing script tools to work directly with maps, layouts, and other project elements.
  • Inventory scripts that log information about projects, data, broken data sources, folder connections, and more.
  • Update, repair, or replace layer data sources.
  • Manage project items such as layouts, maps, reports, folder connections, views, and more.
  • Modify a layer's symbology.
  • Automate sharing project items to be hosted in your organization online.

Intended audience and purpose

Arcpy.mp was built for the professional GIS analyst and for developers. Traditionally, the scenarios listed above had to be performed using the .NET SDK, and it often proved to be a difficult programming environment to learn for the average GIS professional. Arcpy.mp is a coarser-grained object model, meaning that the functions are designed in a way that a single function can replace many lines of finer-grained .NET code. The following is a simple example of how arcpy.mp can be used to reference an existing layout in a project and export it to a PDF document with only four lines of code:

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main Attractions*")[0]
lyt.exportToPDF(r"C:\Project\YosemiteNP\Output\Yosemite.pdf", resolution=300)

The first line loads the arcpy module and is required for all scripts that are run external to ArcGIS Pro. The second line references an ArcGIS Pro project on disk. The third line finds the first layout (using a zero-based index) with a name that begins with the words Main Attractions. The last line of code exports the layout to PDF with an output resolution of 300.

Tips to get started

The best ways to get started include the following:

Beyond the basics

The existing arcpy.mp API can perform some incredible capabilities but also understand that it is not as extensive as the .NET SDK. If there is something you need to accomplish that isn't in the API, it doesn't mean it can't be done. The API has also been designed to allow access to the internal components that persist everything that is saved in a project or layer file. For more information, refer to the Python CIM Access help topic.

Visit the Python Map Automation sample scripts site, where more advanced solutions are available for download.