What is the Mapping module

The Mapping module, arcpy.mp, is a Python module for manipulating the contents of existing project files (*.aprx) or layer files (*.lyrx). You can modify the contents of these files in the application or without the application being open. The module is installed with ArcGIS Pro and is available to all licenses.

The following are some of the many workflows that can be accomplished with an arcpy.mp script:

• Manage project items such as layouts, maps, reports, folder connections, database connections, toolboxes, and styles.
• Access and modify project settings such as default database, default database, and antialiasing mode.
• Generate inventory scripts that log information about projects, layers being used, broken data sources, folder connections, and so on.
• Update, repair, or replace data sources at the project, map, or individual layer level.
• Create or modify a map by changing the extent, adding or removing layers, changing layer symbology, or changing various map properties.
• Modify one of many layer properties such as a definition query, visibility, time settings, symbology, and so on.
• Automate exporting layouts, map views, map series, and reports.
• Create or modify elements on a layout such as changing the page size or orientation, updating a picture, inserting a legend, changing a text string, and so on.
• Extend the capabilities of a map series by including custom logic that generates page-specific changes during export.
• Manage PDF map books by appending, inserting, or deleting pages in a multipage PDF.

Intended audience and purpose

The arcpy.mp module 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. The arcpy.mp module is a coarser-grained object model, meaning that the functions are designed so that a single function can replace many lines of finer-grained .NET code. Example scripts are provided below.

The following script updates the full path of a file geodatabase data source for all layers and tables in a project. In this example, a folder was renamed and all vector data was moved to the new location and the changes are saved to the project. The script can run outside of the application because the project file is referenced using the full path.

import arcpy
aprx = arcpy.mp.ArcGISProject(r'C:\Projects\YosemiteNP\Yosemite.aprx')  
aprx.updateConnectionProperties(r'C:\Projects\YosemiteNP\Old_location\Yosemite.gdb',
                                r'C:\Projects\YosemiteNP\New_location\Yosemite.gdb')
aprx.save()

Note:

For more examples on how to manage data sources, see Updating and fixing data sources.

The following is another example of how arcpy.mp can be used to reference an existing layout in a project and export it to a PDF document using only four lines of code. This script must run inside the application because the current project is being referenced.

aprx = arcpy.mp.ArcGISProject("CURRENT")  
pdf = arcpy.mp.CreateExportFormat("PDF", r"C:\Project\YosemiteNP\Output\Yosemite.pdf")
lyt = aprx.listLayouts("Main Attractions*")[0]
lyt.export(pdf)

Tips to get started

The best ways to get started include the following:

• Follow the Getting started with arcpy.mp tutorial.
• Review Guidelines for arcpy.mp.
• If you used arcpy.mapping in earlier versions of the software and are now using ArcGIS Pro, review Migrating from arcpy.mapping to ArcGIS Pro.
• Review Alphabetical list of arcpy.mp functions and Alphabetical list of arcpy.mp classes to familiarize yourself with the available functionality. These are also helpful printouts to have available when scripting with arcpy.mp.
• All arcpy.mp functions and class help topics have detailed explanations and contain sample snippets of code that can be copied and pasted directly into the Python window, a notebook, a script tool, or a Python IDE.
• Visit the Python Map Automation sample scripts page, where more advanced solutions are available for download.

Beyond the basics

The existing arcpy.mp API can access many of the common capabilities used for automation, but 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 is designed to allow access to the internal components that persist everything that is saved in a project or layer file. For more information, see the Python CIM access help topic for more advanced access to additional capabilities.