Skip To Content

Upgrade a base deployment with ArcGIS Enterprise Builder

Beginning at 10.6, ArcGIS Enterprise Builder can upgrade a base deployment previously installed by the builder. The same limitations apply as with installation.


Deployments set up using another method cannot be upgraded using the ArcGIS Enterprise Builder.

Steps to upgrade

  1. Review and complete prerequisite steps.
  2. Undeploy and uninstall your previous ArcGIS Web Adaptor instances, then install and deploy 10.9 Web Adaptor instances.
  3. Run the ArcGIS Enterprise 10.9 Builder installation program to install 10.9 components.
  4. Use the configuration wizard or upgradebasedeployment command line utility to perform the upgrade.
  5. Complete post-upgrade steps.


If you are upgrading to 10.9, you may need to re-authorize your software for 10.9. If you are upgrading from a version within the same release series, for example from 10.7 to 10.7.1, you do not need to obtain new authorization files. If you are upgrading from a version from a prior release series, you will need to re-authorize your software. You can access your new authorization files in My Esri, along with the ArcGIS Enterprise Builder file.

Review the system requirements for the ArcGIS Enterprise Builder.

Upgrade your ArcGIS Web Adaptor instances

The ArcGIS Enterprise Builder cannot upgrade ArcGIS Web Adaptor, as an additional step is needed to undeploy the Web Adaptor from your Java web server. Perform these steps prior to running ArcGIS Enterprise Builder.

  1. Browse to your ArcGIS Web Adaptor installation folder as an administrator.
  2. Uninstall the instance of ArcGIS Web Adaptor file from the machine. This will undeploy the Web Adaptor instances from your web server.
  3. Undeploy both instances of ArcGIS Web Adaptor from your application server.
  4. Install ArcGIS Web Adaptor 10.9.
  5. Deploy two instances of ArcGIS Web Adaptor to your application server using the arcgis.war file; one for ArcGIS Server and one for the ArcGIS Enterprise portal.

    You can now continue the ArcGIS Enterprise Builder upgrade process.

Run the ArcGIS Enterprise 10.9 Builder setup program

ArcGIS Enterprise Builder is designed to detect and upgrade an existing installation of ArcGIS Enterprise Builder components. To start the upgrade, run ./Setup from the location where ArcGIS Enterprise Builder was extracted, and follow the prompts to complete the upgrade of the ArcGIS Enterprise Builder components. The setup must be run as the user account that installed the existing ArcGIS Enterprise Builder components.

When running the Setup, the ArcGIS Server authorization files can be passed using the same method documented in Installing ArcGIS Enterprise Builder silently, or after the Setup has completed using the Software Authorization tools found in the ArcGIS Server tools folder. This is installed to <EnterpriseBuilderInstallPath>/arcgis/server/tools/authorizeSoftware. Please note, the installation path cannot be changed during an upgrade.

Upgrade using the configuration wizard

You can use the configuration wizard to upgrade ArcGIS Enterprise, or close the browser and use the upgradebasedeployment command line utility to complete your base deployment's upgrade. To use the configuration wizard, complete the following steps:

Once the Setup has run to completion, if it's not already open, browse to the configuration wizard's URL ( You can also search your machine for the ArcGIS Enterprise Configuration Wizard and launch it using the shortcut.


Do not close or refresh the browser when the upgrade is in progress.

  1. The initial landing page appears and explains that the wizard needs to use a secure connection. Click Next.
  2. You are then redirected to secure port 6443 where the browser shows a security warning; this is expected the first time you access the secure wizard. Continue past the warning (this varies by browser).

The ArcGIS Enterprise Builder upgrade wizard comprises three pages:

  1. On the Import License File page, browse to your portal .JSON file containing authorized user types and app bundles. This file is obtained from My Esri.
  2. On the second page, click Upgrade. This triggers the upgrade and creates a backup of your portal's content, site information, and security settings. This step will take a few minutes to complete.
  3. The third page displays the upgrade progress.
  4. When the upgrade wizard is complete, a final page will confirm this. Exit this page to follow the post-upgrade steps in the next section.

Upgrade using the command line utility

Once you've installed the software with ArcGIS Enterprise Builder, complete the upgrade of your base deployment using the command line utility. In order to run the command line utility, you must choose to run it as administrator.

The upgradebasedeployment command line utility is located in <ArcGIS Server installation directory>\tools\upgradebasedeployment.

By default, that location is /home/linux/arcgis/server/tools/upgradebasedeployment.

The following describes the parameters used in the command line utility:

  • -lf —Specifies the path to the portal .JSON license file. If you are upgrading to a version within the same release series, this property is ignored and you can import a new license file after upgrading if needed. The portal .JSON license file is obtained from My Esri.
  • -s —Upgrade the base ArcGIS Enterprise deployment silently with no prompt.
  • -h —Displays help and exits the program.

  1. Open a command prompt.
  2. In the command prompt, change the working directory to the location of the upgradebasedeploymentutility. For example: <ArcGIS Server installation directory>\tools\upgradebasedeployment.
  3. Type the upgradebasedeployment command and parameter directly within the command prompt.
  4. ./ -lf <path to portal json file> -s

Post-upgrade steps

Once you've completed the upgrade wizard steps, you are provided with links to the portal and server.

  1. Verify that you can sign in to the ArcGIS Enterprise portal website through the ArcGIS Web Adaptor URL as an Administrator of your organization. The URL is formatted

    Check the index using the ArcGIS Portal Administrator Directory. If it's out of sync, reindex Portal for ArcGIS.

  2. If you've configured ArcGIS Pro licenses with your organization, optionally upgrade ArcGIS License Server Administrator. When upgrading ArcGIS License Server Administrator, members with ArcGIS Pro licenses will be unable to access ArcGIS Pro. If members are currently logged in to ArcGIS Pro, they will see a message stating that the program will be closed in 24 hours. Members can complete or save their work within this time period. You are not required to reconfigure ArcGIS Pro licenses after upgrading ArcGIS License Server Administrator.
  3. Restore any customization you previously configured for your ArcGIS Enterprise portal. When restoring your portal customizations in 10.9, it's recommended that you do not replace the files you modified in the previous version in 10.9. This may adversely affect your 10.9 deployment. You need to open each file at 10.9 and manually re-add your custom behavior from the previous version.


Esri recommends using the and scripts to check for security best practices with your upgraded ArcGIS Server and ArcGIS Enterprise portal.