← Back to Blog
ArcGIS API for Python · Migration

Migrating to the new arcgis.map module in ArcGIS API for Python 2.4

July 27, 2026 · 8 min read

The arcgis.mapping module splitting into two new arcgis.map and arcgis.layers modules in ArcGIS API for Python 2.4

The 2.4 release of the ArcGIS API for Python quietly rewrote how you work with maps. If you have a notebook that does from arcgis.mapping import WebMap, or automation that leans on gis.map() and its MapView, upgrading to 2.4 will break it — the entire arcgis.mapping module is gone, refactored into two new modules with new class names and new access patterns.

This isn’t a deprecation warning you can defer for a year. In 2.4 the old import path no longer resolves, and the methods you called on a WebMap or a MapView now live on manager objects hanging off a new Map class. The good news: the migration is almost entirely mechanical once you have the mapping tables in front of you. Here is what changed, why Esri did it, and exactly how to move your code.

The breaking change: arcgis.mapping is removed in 2.4. WebMap and WebScene are deprecated, the arcgis.widgets.MapView widget is refactored away, and their functionality moves into the new arcgis.map and arcgis.layers modules. Pin your environment before you upgrade a production notebook.

What changed in 2.4 — and why

The 2.4 release re-architected the Python API to align with the Jupyter Lab 4.0 and Notebook 7.0 backend, so that the map widget renders and behaves the way the browser-based Map Viewer and Scene Viewer do. Esri describes it as “a complete overhaul of fundamental structures” — which meant removing some modules and classes outright and transferring their functionality into new ones. The most visible casualty is the old arcgis.mapping module, which has been split into two:

  • arcgis.map — the map/scene widget and everything you interact with in a notebook: the Map and Scene classes, content and basemap managers, popups, renderers, legends, and time sliders.
  • arcgis.layers — the service and layer data types: map image layers, scene layers, OGC layers, and the new Service helper.

Before you touch anything, check compatibility. The 2.4.0 release is supported with ArcGIS Pro 3.4 and later cloned environments, ArcGIS Enterprise 11.4 and later, and stand-alone conda and Python environments. The series has moved quickly since — 2.4.2 (October 2025) upgraded the primary interpreter to Python 3.13, and 2.4.3 (March 2026) added support for the ArcGIS Enterprise 12.0 beta — so confirm your interpreter and Enterprise versions against the release notes before upgrading a shared environment.

WebMap becomes Map

The WebMap class is deprecated; its functionality moves to the Map class in arcgis.map. You still initialize it from a web map item — the argument name just changes from webmapitem to item:

# 2.3.x and prior
from arcgis.mapping import WebMap
wm = WebMap(webmapitem=item)

# 2.4.x and after
from arcgis.map import Map
wm_item = gis.content.get("<web_map_id>")
wm = Map(item=wm_item)

The bigger adjustment is that the flat methods and properties you called directly on a WebMap now live on manager objects. Layers and tables are reached through a MapContent object at m.content; the basemap through a BasemapManager at m.basemap. The most common operations map like this:

WebMap (2.3 and prior)Map (2.4)Notes
wm.add_layer()m.content.add()via MapContent
wm.layersm.content.layersMapContent property
wm.get_layer()m.content.layers[i]index into the list
wm.remove_layer()m.content.remove(i) 
wm.basemapm.basemap.basemapBasemapManager
wm.configure_pop_ups()m.content.popup(i)new PopupManager
wm.update_drawing_info()m.content.update_layer(renderer)renderer via RendererManager
wm.bookmarksm.bookmarks.listnew Bookmarks class
wm.save() / wm.update()m.save() / m.update()unchanged names

A few members were dropped with no direct replacement — wm.events, wm.height, wm.width, wm.navigation, wm.scale_bar, and wm.search among them. If your code touches any of those, budget time to rethink that piece rather than find-and-replace it.

The map widget: MapView becomes Map (or Scene)

The old arcgis.widgets.MapView was the interactive map you got back from gis.map(). In 2.4 that single class is split in two: gis.map() still accepts a mode argument, but the default "2D" now returns a Map object and "3D" returns a Scene. Aligning with the web map and web scene specifications is what lets the notebook widget mirror the browser experience.

# 2.3.x: always a MapView, regardless of mode
mview = gis.map("Redlands, CA")
mview.add_layer(flayer)

# 2.4.x: a Map (2D) or Scene (3D); layers go through .content
m = gis.map("Redlands, CA")        # -> arcgis.map.Map
m.content.add(flayer)
m.legend.enabled = True              # new Legend widget

Note the removals here, because they bite hardest: the interactive event hooks are gone. on_click() and on_draw_end() have no replacement, and so do embed(), take_screenshot(), display_message(), and the various methods that manipulated the Jupyter window. Everything else refactors cleanly:

MapView (2.3 and prior)Map (2.4)Notes
mview.add_layer()m.content.add()via MapContent
mview.clear_graphics()m.content.remove_all() 
mview.draw()m.content.draw() 
mview.zoom_to_layer()m.zoom_to_layer()unchanged name
mview.legendm.legend.enabled = Truenew Legend widget
mview.time_sliderm.time_slider.enabled = Truenew TimeSlider widget
mview.tilt / mview.headingscene.tilt / scene.heading3D → Scene
mview.on_click() / on_draw_end()removedno replacement
mview.embed() / take_screenshot()removedno replacement
The new widgets are a net gain. The Map class ships first-class legend, layer_list, and time_slider widgets you toggle with a single property. On the Scene side you also get environment.daylight_enabled and environment.weather_enabled — interactive daylight and weather controls in the notebook. If you were hand-rolling any of that before, delete it.

arcgis.layers and the new Service class

Most of the old arcgis.mapping data-type classes — map image layers, scene layers, OGC layers, map service layers — moved into arcgis.layers. Alongside them, 2.4 adds a genuinely useful convenience: the Service class. You no longer have to know which specific class to import for a given service URL; hand Service a URL or item and it returns the correct object type automatically.

# 2.3.x: you had to import the exact class
from arcgis.features import FeatureLayerCollection
fcoll = FeatureLayerCollection(url="…/FeatureServer", gis=gis)

# 2.4.x: Service resolves the type for you
from arcgis.layers import Service
fcoll   = Service(url_or_item="…/FeatureServer", server=gis)   # -> FeatureLayerCollection
svc     = Service(url_or_item="…/MapServer",     server=gis)   # -> MapImageLayer
scene   = Service(url_or_item="…/SceneServer")                # -> Object3DLayer

For scripts that ingest arbitrary service URLs — inventory crawlers, migration tools, anything that can’t assume a service type up front — this removes a whole branch of isinstance guessing. It is the one change in 2.4 that makes new code cleaner rather than merely different.

Migrate in six steps

  1. Pin and clone first. Snapshot your working environment (conda clone or a pinned requirements) so you can roll back; never upgrade a production notebook in place.
  2. Grep for the old imports: arcgis.mapping, WebMap, WebScene, and arcgis.widgets / MapView. That list is your migration surface.
  3. Swap the imports — WebMap → Map and WebScene → Scene from arcgis.map; layer/service classes and Service from arcgis.layers.
  4. Rewire layer and basemap calls through the managers: add_layer → content.add, layers → content.layers, basemap → basemap.basemap, popups and renderers through content.
  5. Flag the removals — on_click, on_draw_end, embed, take_screenshot, events. These need a rethink, not a rename; isolate them before you run anything.
  6. Render and verify in a fresh notebook: open a web map with Map(item=…), add a layer, toggle legend, and confirm the widget draws before you cut the old environment loose.

Because the surface is mostly mechanical, the migration is well suited to a scripted find-and-replace pass followed by a manual review of the removed-members list. Where we do this for clients, the long pole is never the renames — it’s the handful of notebooks that quietly depended on on_click or an embedded screenshot, which now need a different design entirely.

References

Upgrading a fleet of ArcGIS notebooks to 2.4?

We migrate ArcGIS API for Python automation to the new arcgis.map and arcgis.layers modules, pin and clone your environments for a safe rollback, and re-design the handful of notebooks that depended on removed interactivity — without breaking the pipeline.

Book a free intro call