Skip To Content

Upgrade ArcGIS Notebook Server

Upgrading ArcGIS Notebook Server provides your organization with the latest features and improvements to the software, while preserving your users' existing ArcGIS Notebooks. If you are upgrading your ArcGIS Enterprise deployment to 10.8.1, you must also upgrade ArcGIS Notebook Server.

The ArcGIS Notebook Server 10.8.1 setup package detects whether you have an existing installation of a previous version of ArcGIS Notebook Server on your machine. If you do, it can upgrade the software to 10.8.1.

During the upgrade process, you must reauthorize your ArcGIS Notebook Server software for 10.8.1 if you have upgraded from 10.7.1 or earlier. You do not need to reauthorize your software if you are upgrading from 10.8 to 10.8.1.

You must also install new container images from Esri, providing your users with 10.8.1 notebook runtimes. The notebook runtimes from the previous version will remain in the site; users will still be able to run notebooks using those runtimes. However, if your users want to use functionality that is new at 10.8.1, they must update the runtime of their notebooks. The notebook runtimes corresponding to 10.8.1 are at version 4.0 (ArcGIS Notebook Server Standard 4.0 and ArcGIS Notebook Server Advanced 4.0).

Upgrading the ArcGIS Enterprise portal will also update the sample notebooks available in the site's gallery.

Multiple-machine ArcGIS Notebook Server sites are supported at 10.7.1 and later. If you have a single-machine site and want to expand your ArcGIS Notebook Server site to multiple machines after upgrading, follow the steps to join additional machines to the site after you have finished upgrading to 10.8.1.

The upgrade process for ArcGIS Notebook Server is an in-place upgrade, which does not require uninstalling and reinstalling software. The site will be down during the upgrade process, and users will be unable to access or run notebooks until the upgrade is complete.

Follow the steps below to upgrade ArcGIS Notebook Server to 10.8.1.

Prepare to upgrade

Before upgrading, carefully review the following information:

  • You can access all of the necessary files in My Esri before upgrading, including the 10.8.1 container images.
  • For ArcGIS Notebook Server to function correctly, its version must match the version of the portal with which it's federated.
  • To upgrade your ArcGIS Enterprise deployment, do the following:
    1. Upgrade Portal for ArcGIS.
    2. Upgrade ArcGIS Web Adaptor (for Portal).
    3. Upgrade the ArcGIS Server site serving as the portal's hosting server.
    4. Upgrade ArcGIS Web Adaptor (for Server).
    5. Upgrade ArcGIS Data Store (upgrade primary first, and then standby).
    6. Upgrade any other servers, including ArcGIS Notebook Server.
  • Do not uninstall the existing ArcGIS Notebook Server. ArcGIS Notebook Server setup and command line installers are designed to detect and upgrade an existing installation of ArcGIS Notebook Server components.
  • Do not unfederate your ArcGIS Notebook Server site from the portal or remove its designation as the portal's Notebook Server at any point during the upgrade process. This adversely impacts the existing ArcGIS Notebooks hosted by the portal.
  • You can upgrade ArcGIS Notebook Server using either the Setup or Command line installer. Choose one of the methods to upgrade.
  • Before upgrading, clear the caches of all web browsers used on the ArcGIS Notebook Server machine.
  • The Windows service account for your ArcGIS Notebook Server site (its Run As account) must remain the same when upgrading.

Back up your deployment

Before you upgrade, it's recommended that you make backups of your deployment.

In 10.7, you must manually back up the site's configuration store and server directories.

Notebooks will be included in portal backups using the webgisdr utility.

You can use the exportSite operation in the ArcGIS Notebook Server Administrator Directory to back up a site's configuration store, as described below. In addition to this site configuration backup, consider making manual backups of your file system.

Perform the following steps to execute the backup operation:

  1. Open the ArcGIS Notebook Server Administrator Directory and sign in as a user with administrative privileges. The URL is typically
  2. Browse to site > Export Site.
  3. Enter the full path of the location on your machine to which you want to export the file. The site must have access to this directory.
  4. Click Export.
  5. When the export operation is complete, the directory will provide a link to the backup file location on the server. Download the file, which will have an .agssite file extension, as promptly as possible.

Upgrade using the setup program


It is recommended that you use the setup file to upgrade ArcGIS Notebook Server to 10.8.1. If organizational restraints prevent you from using the setup file, you can call the Upgrade Site operation from the ArcGIS Notebook Server Administrator Directory using a script.

If you have a multiple-machine site, follow steps 1 through 5 for one machine, and then repeat those steps for each machine in the site.

  1. During the installation, read the master agreement and accept it, or exit if you do not agree with the terms.

    The setup program displays the feature that will be installed and the free disk space it requires on your hard drive.

  2. On the next dialog box, either specify the account login credentials or provide a configuration file.

    The ArcGIS Notebook Server account used by your existing installation is prepopulated in the ArcGIS Server Account box. Provide the password for the ArcGIS Notebook Server account. Typically, this is the password you defined when installing the software.

    If the password is not validated successfully, an error message appears, indicating that the password is invalid. If you are unsure of the password for the ArcGIS Notebook Server account, contact your system administrator or reset your password using the ArcGIS Notebook Server Administrator Directory.

    If you provide a configuration file, the credentials in the server configuration file must be the same credentials used by your existing ArcGIS Notebook Server site.

  3. If you selected Specify the account name and password and manually entered the ArcGIS Notebook Server account information, you can export a server configuration file on the dialog box that appears. If you do not want to export a configuration file, click Next and accept the default Do not export configuration file option. If you want to export a server configuration file for future installations, click Export configuration file, browse to a secure folder, and provide a name for the configuration file.

    You may want to export a server configuration file if you need to do any of the following:

    • Create the same ArcGIS Notebook Server account when installing on multiple machines.
    • Store the account for use when upgrading to a newer version.
    • Perform a silent installation in which the user name and password are encrypted.


    When exporting a server configuration file to a network share, the Local System account on the machine where ArcGIS Notebook Server is being installed must have write permissions to the network share. If the permissions are not set, the server configuration file may not export successfully. If you're unsure how to correctly set permissions for the network share, contact your system administrator, or export the server configuration file locally and copy it to the network share.

  4. To complete the installation, follow the directions on the screen.
  5. After installation is complete, the configuration wizard opens in a browser. Follow the instructions provided in the configuration wizard to complete the upgrade process.
  6. If you have a multiple-machine site, proceed to follow steps 1 through 5 for the rest of your site's machines. If you have a single-machine site and plan to upgrade to a multiple-machine site, you can now join the additional machines to the site. You must also modify the paths of the server directories and of the configuration store to use shared locations accessible to each machine. The exceptions are the workspace directory and any custom data directories, which must remain local to each machine and replicated using a system such as DFS.

Upgrade from the command line

You can also upgrade ArcGIS Notebook Server from the command line using the upgradesite utility starting at 10.8.

This utility only has two parameters:

  • -s—When included in the command, this prompts the utility to run the upgrade. The upgrade won't run without -s. This is intended as a safeguard to ensure you only run the upgrade when you're ready.
  • -h—Displays the help for the tool. When the command is run without -s, the help also displays.

By default, the upgradesite utility is found at C:\Program Files\ArcGIS\NotebookServer\tools\upgradesiteutility\upgradesite.bat.

Before upgrading, review the preparation information at the beginning of this topic. When you are ready to upgrade, open a command terminal on the machine you're upgrading. Browse to the directory where the utility is located, and run the following command:

> upgradesite.bat -s

The utility will display progress reports and stop when the upgrade is complete. If you have multiple machines in your site, repeat this command on each machine, then continue to the steps in the next section.

Authorize silently

After the upgrade utility has completed, you must reauthorize your ArcGIS Notebook Server software for 10.8.1 if you have upgraded from 10.7.1 or earlier. You do not need to reauthorize your software if you are upgrading from 10.8 to 10.8.1.

Run SoftwareAuthorization.exe with the following syntax to authorize ArcGIS Notebook Server silently. You must have all user information complete in the authorization or provisioning file before running the file.

If you have an authorization file and your machine is connected to the internet, run the following:

<System disk drive>\Program Files\Common Files\ArcGIS\bin\SoftwareAuthorization.exe /S /Ver 10.7 /LIF <full path and name of authorization file>

Authorize in a disconnected environment

You can authorize ArcGIS Notebook Server in a disconnected environment using a provisioning (.prvc) file. During the process, a file will be generated for you to send to Esri to complete the process.

  1. At the prompt, run the command provided below after the ArcGIS Notebook Server upgrade is complete:

    <System disk drive>\Program Files\Common Files\ArcGIS\bin\SoftwareAuthorization.exe /F <full path to the .prvc file> /O <full path to authorization file output>

  2. When the output information file has been created, do one of the following:
    • Browse to the Esri customer service website at Follow the instructions on the screen to upload your authorization information file and download your .ecp authorization file.
    • Send your authorization information file by email to Esri will send your .ecp authorization file back to you in an email.
  3. When you have received your .ecp authorization file using either above method, run the authorizeSoftware script again to process it and complete the server authorization process:

    <System disk drive>\Program Files\Common Files\ArcGIS\bin\SoftwareAuthorization.exe /F <full path to the .ecp file>

Repeat this workflow for each machine running ArcGIS Notebook Server.

Steps after upgrading

Before your upgraded and reauthorized ArcGIS Notebook Server site can be used, you must run the postinstallation utility to add your new Docker container images to the site. You must also replace the ArcGIS Web Adaptor instances registered with your site to match the new version.

  1. Open the command prompt window using the ArcGIS Notebook Server Run As account.
  2. Install your Docker image by specifying its file path. The image should be zipped in the .tar.gz format. If you have an Advanced license, run the command twice to install both the Standard and Advanced container images you downloaded from My Esri. > PostInstallUtility.bat -l <path of .tar.gz Docker image>

    Ensure you install both container images. Even if you have the Advanced license, your users may still need to use the Standard runtime.

  3. Unregister the previous instance of ArcGIS Web Adaptor from your site and uninstall.
    1. Login to your ArcGIS Notebook Server Administrator Directory.
    2. Browse to System > Web Adaptors > registered machine.
    3. Click Unregister Web Adaptor.
  4. Install a new instance of ArcGIS Web Adaptor 10.8.1 and register it with ArcGIS Notebook Server.
  5. Once your deployment upgrade is complete, you can take advantage of 10.8.1 functionality. To enable scheduling of notebooks in your portal, do the following:

Your ArcGIS Notebook Server 10.8.1 site is now ready to host ArcGIS Notebooks.