Update Esri vector basemaps for the United States in ArcGIS Enterprise via Python

Summary

With the latest update of the Esri vector basemaps on February 20, 2025, there is a new set of custom basemaps for the United States. These basemaps include updated place names recently defined by the U.S. Government, as well as updated treatments of several disputed boundaries and places previously defined by the U.S. State Department.

The workflow for manually adding these new United States vector basemaps ArcGIS Enterprise is outlined in Esri Vector Basemaps for United States and ArcGIS Enterprise blog.  This article outlines the steps to update the Esri vector basemaps for United States in ArcGIS Enterprise via Python with the US vector basemaps script.

To use this script, download the attached file and follow the instructions provided below. For questions and feedback about using the script, comment on this Esri Community post.  Esri Technical Support may assist you in running the script to troubleshoot an ongoing issue, but cases specifically related to modifying or extending the script are outside of the Scope of Support. Formal bugs or enhancement requests cannot be logged against this script.

Procedure

Setup

1. Download and extract the us_vector_basemaps.zip file to a machine that has either ArcGIS Server or ArcGIS Pro installed. Either ArcGIS Server or ArcGIS Pro is required as they include the necessary Python environment for the Configuration reporter to run.
2. Open the us_vector_basemaps folder.
3. Open the config.ini file in a text editor (Notepad or Notepad++ is recommended).
4. Add your Enterprise portal URL to target_portal (portal web context URL).
5. Add your administrator username to admin_username.
6. Add your administrator password to admin_password.
7. Add the name of the user who will own the new vector basemaps to portal_maps_owner.  This user must be an adminstrator in the organization.
8. Add a folder name in the user’s ArcGIS Enterprise portal content directory to portal_maps_folder. This is where the vector basemaps are copied to. This folder must already exist in the ArcGIS Enterprise portal user’s content directory. In the example below, the folder is called newMaps.
9. Save the file and close it.

The following image shows the viewpoint from the ArcGIS Enterprise portal user content folder where the vector basemaps is copied to:

Run the script

1. Open a Command Prompt window as an administrator.
2. Change the directory to where you saved the us_vector_basemaps folder.

Example:

cd C:\Scripts\us_vector_basemaps

3. While in this directory you will need to call the Python environment that runs the US Vector Basemaps script. The Python environment can be called from your ArcGIS Server installation or ArcGIS Pro installation.
   • Additionally, these paths can vary if the default installation paths are not used. If you have used a different drive letter or installation location, locate your ArcGIS Server or ArcGIS Pro’s python.exe.

If using the ArcGIS Server Python environment
By default, ArcGIS Server's Python environment can be found at:

C:\Program Files\ArcGIS\Server\framework\runtime\ArcGIS\bin\Python\envs\arcgispro-py3\Python.exe

Syntax for running script with ArcGIS Server's default installation path:

C:\Scripts\us_vector_basemaps>"C:\Program Files\ArcGIS\Server\framework\runtime\ArcGIS\bin\Python\envs\arcgispro-py3\python.exe" update_us_basemaps.py

If using the ArcGIS Pro Python environment
By default, ArcGIS Pro's Python environment can be found at:

C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3>python.exe

Syntax for running script with ArcGIS Pro's default installation path:

C:\Scripts\us_vector_basemaps>"C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" update_us_basemaps.py

Note:
If you are using ArcGIS Pro, the machine that has ArcGIS Pro installed must be able to communicate with the machine(s) where the Portal for ArcGIS and ArcGIS Server components are deployed.)

Script output

When the script runs, the command prompt prints the progress of each step:

Updating the ArcGIS Enterprise organization’s basemaps

Once the script has run, the ArcGIS Enterprise organization’s basemap gallery must be updated.  The steps for this are outlined in the ArcGIS Enterprise product documentation.

Summary

1. Log in to ArcGIS Enterprise as the user who owns the maps.
2. Navigate to the folder where the vector basemaps were copied to.  Note that the new web maps are in the folder, as in the example image below.

3. Create a new group, for example, Esri US Vector Basemaps.
   • Make sure the group membership’s Who can view this group? setting is set to Everyone or All Organization members, based on your organization’s access needs.

4. Navigate back to the folder where the new vector basemaps are located.
5. Select all basemaps and share them:
   • Set sharing level to Organization or Everyone (public) based on your organization’s access needs.
   • Set group sharing to the example group created in step 3, Esri US Vector Basemaps.

6. You may be prompted that the shared item(s) reference other items that may not be visible because they are shared differently. Click Review sharing to update the sharing of the listed items, as shown in the next two images.

7. All items should now be shared to the new basemap group.  Navigate to the Organization > Settings > Map directory.

8. Under Basemap gallery, select the pencil icon to update the group whose web maps will be shown in the basemap gallery. In the photo above, it is listed as Default.
9. Select the group with the new Vector Basemaps, in the example, Esri US Vector Basemaps.

Verify

1. Open a new web map and zoom in so that labels are visible.
2. Note the Gulf of America label is present by default.

3. Use the Basemap selection widget to cycle through other basemaps.