Skip To Content

Migrating from arcpy.mapping to ArcGIS Pro

Arcpy.mapping scripts authored with ArcGIS Desktop will need to be modified before they will run in ArcGIS Pro. The changes are straight-forward and logical and can be accomplished mostly with find and replace operations. The sections below highlight many of the significant changes to the arcpy.mp API as well as new features that were added.

Python 3

One thing to keep in mind is that ArcGIS Pro uses Python 3. It is possible that you will need to modify some standard Python syntax. If you want to run stand-alone Python scripts you are required to install 64-bit Python.

Arcpy.mapping is now arcpy.mp

As you will see below, the changes introduced with ArcGIS Pro were significant enough to merit a module name space change. The new name also offers more flexibility in terms of the capabilities arcpy.mp can offer. For example, in addition to map automation, arcpy.mp can also provide project level management.

The ArcGIS Pro project file (.aprx)

The first and most obvious change is that arcpy.mp in ArcGIS Pro needs to reference a project file (.aprx) rather than a map document (.mxd). Therefore, arcpy.mapping.MapDocument(mxd_path) needs to be replaced with arcpy.mp.ArcGISProject(aprx_path). The ArcGISProject function returns an ArcGISProject object which is a main entry point for most arcpy.mp automation needs. The two objects are similar, but there is a different collection of methods and properties. One important difference is a method named importMapDocument. It enables you to automate the importing of map (.mxd), globe (.3dd), and scene (.sdx) documents into a project.

Many of the list functions have moved

Many of the stand-alone arcpy.mapping List functions are now methods on the appropriate objects. This design change removed the need to continually have to reference the map document as the first parameter, and the new organization has a much better object-oriented flow. The following examples demonstrate how list functions are used to reference a layer's label classes. They are very similar in terms of functionality, but it will require changes to your existing ArcGIS Desktop scripts.

This sample demonstrates how to reference a layer's label classes using ArcGIS Desktop.

mxd = arcpy.mapping.MapDocument("CURRENT")
df = arcpy.mapping.ListDataFrames(mxd, "Yosemite National Park")[0]
for lyr in arcpy.mapping.ListLayers(mxd, df):
    if lyr.supports("SHOWLABLES"):
        lblClasses = lyr.labelClasses

This sample demonstrates how to reference a layer's label classes using ArcGIS Pro.

p = arcpy.mp.ArcGISProject("CURRENT")
m = p.listMaps("Yosemite National Park")[0]
for lyr in m.listLayers():
    if lyr.supports("SHOWLABELS"):
       lblClasses = lyr.listLabelClasses()

The following diagram displays the classes that are part of arcpy.mp and the location and name of the functions or properties needed to reference a particular class.arcpy.mp OMD overview

Export functions have moved

The stand-alone export functions are now methods on the Layout and MapFrame objects. The design change separates the different sets of parameters that are available depending on the object being exported. For example, when exporting a Layout, it does not make sense to include world file information.

Layer management functions have moved

The stand-alone layer management functions are now methods on the Map and LayerFile objects. The methods include addLayer, addLayerToGroup, insertLayer, moveLayer, and removeLayer.

Layer files have changed

Layer files authored with ArcGIS Desktop have a .lyr extension, and layer files created with ArcGIS Pro have a .lyrx extension. There is a notable difference. Older .lyr files only store a single layer or a single group layer at the root level, although a group layer can have multiple layers or group layers within it. Newer .lyrx files can store multiple layers and/or group layers at the root level. A reference to a .lyrx can now be a reference to either a single layer or a list of layers.

New Map, MapFrame, and Camera objects replace the role of the data frame

The ArcGIS Pro framework has introduced new capabilities that affect how you interact with map displays and therefore new objects are being introduced. These new Map, MapFrame, and Camera objects each serve a specific role and are tightly integrated with one another.

A Map in ArcGIS Pro represents a collection of tabular and symbolized geographic layers and also persists information such as coordinate system, default views of the data, and various other metadata. The only way to visualize the contents of a map is in a map view, as a tab in the application with its own table of contents, or in a mapframe on a page layout. The same map can be displayed in multiple map views or map frames. If a layer is added to a map, all map views and map frames that reference that map will display the added layer. If you want a different collection of layers or tables to be displayed in different views, you will need to build and use different maps.

A MapFrame is a Layout element that displays the geographic information added to a Map. It also controls the size and positioning of itself on a layout. More than one MapFrame can reference the same Map.

The ArcGIS Pro application integrates 2D and 3D display and therefore the Camera object is used to control both the scale and extent for 2D maps and the camera position for 3D maps in a MapFrame.

A new Layout object

An ArcGIS Pro project supports multiple layouts. As a result, a new Layout object was added and layouts can be referenced by using the listLayouts method on the ArcGISProject object. Each layout can have different page sizes and orientations. Similar to ArcGIS Desktop, you can get to the individual layout elements using the listElements method. Each of these elements has a visible property that allows you to turn off an element rather than having to move it off the page.

The application always refreshes when using CURRENT

When using the CURRENT keyword in the Python window with ArcGIS Desktop, you sometimes had to call refreshActiveView to force a screen refresh. This is no longer the case with ArcGIS Pro. All arcpy.mp API changes will directly update the application.

Updating data sources has changed

The methods and parameters for changing a layer or table's data source has changed significantly. This improved design allows for better management for database connections as well as other datasources that may be joined or related. For more information, refer to the Updating and Fixing Data Sources help topic.