Skip to main content

Deploy custom Python packages for ArcGIS Server

A Python 3 based conda environment is included with ArcGIS Server. The Python installation of ArcGIS Server includes packages such as numpy and matplotlib. However, if you want to install additional custom Python packages for your script tools and Python toolbox, follow the steps below. Similar to ArcGIS Pro, ArcGIS Server uses conda to manage Python environments. For additional information about using and working with conda, see the introduction to conda.

For more information about the Python environment in ArcGIS Pro, see Python in ArcGIS Pro. It is recommended that you clone the default Python environment to make updates.

Only one Python environment that applies to all geoprocessing services can be active at a time. You can also specify Python environments for individual geoprocessing services if services need their own custom Python environments.

When cloning the environment, ensure the ArcGIS Server account has the Read and Execute permissions on the cloned environment, otherwise Python will not initialize, and none of the Python code in your tool will run.

You need to manually manage the cloned environment during uninstallation. You will also need to manually upgrade a cloned Python environment with the proup command after upgrading ArcGIS Server.

Specify a Python environment for all geoprocessing services

To deploy third-party Python packages with ArcGIS Server for all geoprocessing services, use the following steps for each machine in your site.

Note:

This will also change the Python environment of your system geoprocessing services.

  1. Sign in to your ArcGIS Server machine with the ArcGIS Server account or an account that has access to the default Python environment and the destination directory for the cloned environment.

  2. Launch the Wine explorer to prepare for cloning the default environment.

  3. Run the following command:

    source <install>/framework/etc/arcenv
wine cmd

  4. Once Wine is activated, clone the environment with the following command:

    Note:

    The conda-proclone command does not require internet access.

    Note:

    Ensure the ArcGIS Server account has read and write access to the cloned environment.

    Note:

    The default environment is typically at <install>\framework\runtime\ArcGIS\bin\Python\envs\arcgispro-py3.

    cd "Z:\data\arcgis\server\framework\runtime\ArcGIS\bin\Python\Scripts"
conda-proclone -i <path to default environment>  <path to cloned environment>

    To learn more about conda-proclone, run conda-proclone -h.

  5. Activate the cloned environment by running activate <path to cloned environment> in the Wine command.

  6. Install the custom packages into the activated cloned environment in the Wine command.

    Note:

    Most third-party Python packages will work; however, if the package makes WIN32 calls (directly or indirectly interacting with Windows OS), those packages will not function properly even with a successful configuration.

    The following command is an example of installing the flask Python package.

    conda install flask

  7. Swap your server to the cloned environment with the following command in the Wine command:

    conda proswap -n <cloned environment> --all-users`
    Note:

    If you are using the ArcGIS Server account for the session, the --all-users command is not necessary. If you copy your cloned environment outside the default ~\Python\envs folder, provide the full path to the environment.

    Note:

    All of your geoprocessing services, including the system geoprocessing services, will use the cloned environment after the swap.

  8. Restart your ArcGIS Server service.

  9. Start a new session or exit the Wine command with exit().

    Note:

    The startserver and stopserver scripts are in the scripts directory of your ArcGIS Server installation.

  10. For a multiple-machine deployment, repeat the steps above on all other machines in your ArcGIS Server site.

Specify a Python environment for a single geoprocessing service

Follow the steps below to set up an environment for a single geoprocessing service.

  1. Sign in to your ArcGIS Server machine with the ArcGIS Server account or an account that has access to the default Python environment and the destination directory for the cloned environment.

  2. Launch the Wine explorer to prepare for cloning the default environment.

  3. Run the following command:

    source <install>/framework/etc/arcenv
wine cmd

  4. Once Wine is activated, clone the environment with the following command:

    Note:

    The conda-proclone command does not require internet access.

    Note:

    Ensure the ArcGIS Server account has read and write access to the cloned environment.

    Note:

    The default environment is typically at <install>\framework\runtime\ArcGIS\bin\Python\envs\arcgispro-py3.

    cd "<path to server install>\framework\runtime\ArcGIS\bin\Python\Scripts"
conda-proclone -i <path to default environment>  <path to cloned environment>

    To learn more about conda-proclone, run conda-proclone -h.

  5. Activate the cloned environment by running activate <path to cloned environment> in the Wine command.

  6. Install the custom packages into the activated cloned environment in the Wine command.

    Note:

    Most third-party Python packages will work; however, if the package makes WIN32 calls (directly or indirectly interacting with Windows OS), those packages will not function properly even with a successful configuration.

    The following command is an example of installing the flask Python package.

    conda install flask

  7. Once all the packages are installed, go to the ArcGIS Server administrator directory, and click the services Resource.

  8. Select the geoprocessing service that you want to specify a Python environment for.

  9. In Supported Operations at the bottom of the page, click edit.

  10. In the service JSON, add the key value pair "condaEnvironmentPath": "<full path to cloned-env>" to the service properties.

    Note:

    If you are using a directory outside the ArcGIS Server installation's Python environment directory, you must provide the full path to your cloned environment.

    The following is a simplified service property JSON that includes the condaEnvironmentPath property:

    {
 "serviceName": "regionalAnalysis",
 "type": "GPServer",
 "description": "",
 "allowedUploadFileTypes": "",
 "properties": {
  "toolbox": "Z:\\data\\arcgis\\arcgisserver\\directories\\arcgissystem\\arcgisinput\\Analysis.GPServer\\extracted\\p30\\RegionalAnalysis.tbx",
  "condaEnvironmentPath": <"path to cloned environment">,
  "showMessages": "INFO"
 },
 "portalProperties": {
  "isHosted": false,
  "portalItems": [{
   "itemID": "4921223df97744a593d0b776666b9da9",
   "type": "GPServer"
  }]
 },
 "extensions": [{
  "typeName": "WPSServer",
  "properties": {
   "serviceType": "",
   "name": ""
  }
 }],
 "frameworkProperties": {},
 "datasets": []
}

  11. Click the Save Edits button to save your edits.

The service restarts automatically.

Upgrade a cloned Python environment after an ArcGIS Server upgrade

Previously, when upgrading ArcGIS Server to a newer version, you would need to discard the previously cloned environments. You would then need to clone the Python environment from the upgraded ArcGIS Server and reconfigure your services.

In ArcGIS Server 12.1 and later, you can use the conda proup command to upgrade the cloned Python environments from earlier versions of ArcGIS Server by completing the following steps:

  1. Sign in to your ArcGIS Server machine as the ArcGIS Server account or an account that has access to the cloned environment and the server installation.

  2. Launch the Wine command and change the directory to <install>\server\framework\runtime\ArcGIS\bin\Python\Scripts.

  3. Upgrade the environment by running either conda proup -n <environment name> or conda proup -p <environment directory path>.

  4. After the Python environment upgrade, either restart all of the geoprocessing services used by this conda environment, or restart the ArcGIS Server service.

To learn more about the conda proup command, use conda proup --help. This function cannot be used to downgrade an environment after a downgrade of ArcGIS Server. This function is not available in disconnected environments.

Specify a Python environment for all geoprocessing services

To deploy third-party Python packages with ArcGIS Server for all geoprocessing services, use the following steps for each machine in your site. Note, this will also change the Python environment of your system geoprocessing services.

  1. Sign in to your ArcGIS Server machine and open the command prompt window as an administrator.

    Note:

    You may need administrative privileges depending on the location of your existing conda environment.

  2. Change the directory to <install>\ArcGIS\Server\framework\runtime\ArcGIS\bin\Python\Scripts.

  3. Clone the server's default Python environment with a new environment name using either conda create or conda proclone:

    Note:

    The suggested location is at the ArcGIS Server installation's Python environment directory. Alternatively, you can specify a location to another location the ArcGIS Server account has permissions to access.

    • Use the following command to clone the environment with conda create:

      conda create --clone arcgispro-py3 --prefix <"cloned environment path"> --pinned --no-shortcuts

    • At 12.1 and later, use conda proclone to clone the environment when your ArcGIS Server does not have internet access or if you prefer a local copy of an existing environment for faster processing. You can replace arcigspro-py3 with another existing python environment path as the input environment to be cloned.

      `conda proclone <"cloned environment path"> --input-env arcgispro-py3`

  4. Run conda proswap -n <new environment name> --all-users to activate the cloned environment.

    Note:

    Providing the --all-users argument is optional if you signed in to your machine as the ArcGIS Server account user; otherwise, it is a required argument.

    Note:

    If the cloned conda environment is outside {ServerInstallation}\framework\runtime\ArcGIS\bin\Python\envs\, provide the full path to that location using conda proswap -p "<full-path-to-cloned-directory>" --all-users.

  5. Install third-party Python packages by running conda install.

    Note:

    Only use pip install if conda install is not available.

  6. Restart the ArcGIS Server service.

    Note:

    It will take a few minutes before all services are back online.

  7. Repeat steps 1 through 6 on all other machines in your ArcGIS Server site for a multiple-machine deployment.

Add more packages

To add more packages to the existing conda environment, follow these steps:

  1. Sign in to your ArcGIS Server machine. You may need administrative privileges, depending on the location of your existing conda environment.

  2. From the start menu, open the Python 3 Command Prompt. It may be in the ArcGIS Server folder, depending on your operating system. If it is not available in the start menu, you can run proenv.bat at <install>\ArcGIS\Server\framework\runtime\ArcGIS\bin\Python\Scripts.

  3. Run conda install for the packages that need to be deployed.

    Note:

    Only use pip install if conda install is not available.

  4. Restart the geoprocessing service in ArcGIS Server Manager.

  5. Optionally, restart the ArcGIS Server service.

    Note:

    All services will restart in a few minutes.

  6. If you have a multiple-machine deployment, repeat steps 1 through 5 on each machine in your ArcGIS Server site.

Specify a Python environment for a single geoprocessing service

Clone the server default Python environment, install third-party Python packages, and edit the service properties of your geoprocessing service using the following steps:

  1. Sign in to your ArcGIS Server machine, and open the Python 3 Command Prompt from the start menu.

    It is recommended that you run the command prompt as an administrator, otherwise you may not be able to clone the environment to certain directories.

  2. Clone the server's default Python environment with a new environment name using either conda create or conda proclone:

    Note:

    The suggested location is at the ArcGIS Server installation's Python environment directory. Alternatively, you can specify a location to another location the ArcGIS Server account has permissions to access".

    • Use the following command to clone the environment with conda create:

      conda create --clone arcgispro-py3 --prefix <"cloned environment path"> --pinned --no-shortcuts

    • At 12.1 and later, use conda proclone to clone the environment when your ArcGIS Server does not have internet access or if you prefer a local copy of an existing environment for faster processing. You can replace arcigspro-py3 with another existing python environment path as the input environment to be cloned.

      `conda proclone <"cloned environment path"> --input-env arcgispro-py3`

  3. Activate the new environment in the command prompt window with activate <new environment name>. If you are using a directory outside the ArcGIS Server installation's Python environment directory, provide the full path to the cloned environment with activate <fullpath>\<new environment name>.

  4. Install Python packages with conda install packagename=version.

    It is recommended that you align the package version you used in ArcGIS Pro during the publishing process and the package version installed on the server.

  5. Once all the packages are installed, go to the ArcGIS Server administrator directory and click services in Resources.

  6. Select the geoprocessing service that you want to specify a Python environment for.

  7. In Supported Operations, click edit at the bottom of the page.

  8. In the service JSON, add the key value pair "condaEnvironmentPath": <"new environment name"> or "condaEnvironmentPath": "<full path to new environment>" to the service properties when the cloned environment is in the ArcGIS Server installation's Python environment directory. If you are using a directory outside the ArcGIS Server installation's Python environment directory, you must provide the full path to your cloned environment. The following example is a simplified service property JSON that includes the condaEnvironmentPath property:

    {
 "serviceName": "gvonly",
 "type": "GPServer",
 "description": "",
 "allowedUploadFileTypes": "",
 "properties": {
  "toolbox": "C:\\arcgisserver\\directories\\arcgissystem\\arcgisinput\\gvonly.GPServer\\extracted\\p30\\gvonly.tbx",
  "condaEnvironmentPath": <"new environment name">,
  "showMessages": "INFO"
 },
 "portalProperties": {
  "isHosted": false,
  "portalItems": [{
   "itemID": "4921223df97744a593d0b776666b9da9",
   "type": "GPServer"
  }]
 },
 "extensions": [{
  "typeName": "WPSServer",
  "properties": {
   "serviceType": "",
   "name": ""
  }
 }],
 "frameworkProperties": {},
 "datasets": []
}

  9. Click the Save Edits button to save your edits.

The service restarts automatically.

Upgrade a cloned Python environment after an ArcGIS Server upgrade

Use the conda proup command to upgrade the cloned Python environments from earlier versions of ArcGIS Server by completing the following steps:

  1. Sign in to your ArcGIS Server machine and open the command prompt window as an administrator.

  2. Change the directory to <install>\ArcGIS\Server\framework\runtime\ArcGIS\bin\Python\Scripts.

  3. Upgrade the environment by running either conda proup -n <environment name> or conda proup -p <environment directory path>.

  4. After the Python environment upgrade, restart all of the geoprocessing services used by this conda environment, or restart the ArcGIS Server service.

To learn more about the conda proup command, use conda proup --help. This function cannot be used to downgrade an environment after a downgrade of ArcGIS Server. This function is not available in a disconnected environment either.