Install and set up

There are multiple ways in which you can experience the ArcGIS API for Python and its SDK. The ArcGIS API for Python is distributed as a conda package named arcgis. Conda is a popular Python package and environment manager application that helps you install and update packages such as the ArcGIS API for Python and their dependencies.

See below for options to install both conda and the arcgis package:

Try it live

The API is now available in a live sandbox. You may choose to experience it in the sandbox before going ahead with the installation. Click the link below to launch a temporary Jupyter notebook environment.

Try it live

These are temporary environments which are erased after you close the browser tab. If you would like to save your changes, download your notebooks from the File menu of the Jupyter notebook IDE.

Step 1: Get Conda

Get Conda with ArcGIS Pro

Get Conda with Anaconda for Python Distribution

Anaconda installs Python, conda for package management and many useful Python packages. Since the ArcGIS API for Python requires Python 3.5 or later, proceed to the Anaconda download page and download the appropriate 3x version of the Anaconda software:

Once the Anaconda software is installed, proceed to Install the arcgis package with the Anaconda for Python Distribution to install the API.

Step: 2 Install the arcgis package

Install using ArcGIS Pro Python Package Manager

ArcGIS Pro 1.4 and later provides the Python Package Manager GUI to download and install any conda package. Access it through the ArcGIS Pro backstage area:

  • Open ArcGIS Pro with a new blank Project
  • Select the Project tab to access the Pro backstage (see screen shot below)
  • Select the 'Python' menu option
  • Click the 'Add Packages' button and type arcgis into the search bar
    • You may have to click the 'refresh' button to ensure you get the complete list of available releases. You will be able to install up to release 1.2.5. To upgrade to a package beyond the 1.2.5 release, see Upgrade the arcgis package
  • Select the release you want to install
  • Click 'Install' and accept the terms and conditions

install using ArcGIS Pro

To use the API in different IDEs, proceed to Using the API

Install using Python Command Prompt

  • Navigate to Start Menu > All Programs > ArcGIS > Python Command Prompt
  • Enter the following at the prompt:
    conda install -c esri arcgis
    

python command prompt

To use the API in different IDEs, proceed to Using the API

NOTE: Depending on how you installed Pro, you might have to start this prompt with elevated privileges.

Install using Anaconda for Python Distribution

Open a terminal application and install the API with the following command:

conda install -c esri arcgis

install arcgis package mac

To use the API in different IDEs, proceed to Using the API

Install using pip

Pip is a package management system used to install and manage software packages written in Python, similar to conda. Many pip packages can be found in the Python Package Index (PyPI), including the ArcGIS API for Python pip package. To install the API with pip, open a terminal and enter the following command:

pip install arcgis

Pip and conda are totally seperate package managers, and should avoid being used interchangeably. It is recommended you use conda to install the API if you are a beginner user. Read more about the differences.

Note: when installing the ArcGIS API for Python with pip, some dependencies may require Microsoft Visual C++ 14.0. If you see any errors related to this, either install the Microsoft Visual C++ tools or install the API without dependencies.

Install without Dependencies

Both conda install -c esri arcgis and pip install arcgis will install all of the dependencies outlined in the system requirements section. However, the API can function in a 'stripped down' state with only the six dependency. This means you can manually manage the dependencies on your system if you don't want to use every feature of the API.

To install the API with no dependencies, simply add the --no-deps flag to any install command, i.e. conda install -c esri arcgis --no-deps or pip install arcgis --no-deps. You can then manually choose which dependencies, if any, to add to your Python environment.


Upgrade the arcgis package

ArcGIS Pro 2.1

ArcGIS Pro 2.1 ships with the ArcGIS API for Python 1.2.5 installed. To update to the newest release, proceed to to run the command below from either a Terminal window with the arcgispro-py3 environment active, or the Python Command Prompt:

conda upgrade -c esri --no-pin arcgis

ArcGIS Pro 1.4 and 2.0.x

Python Package Manager
  • Open ArcGIS Pro with a new blank Project
  • Select the Project tab to access the Pro backstage (see screen shot below)
  • Select the 'Python' menu option
  • Use the Project Environment dropdown to chooose the appropriate environment
  • Select the Update Packages option
  • Choose the appropriate arcgis release from the list of packages with recent updates

    python_package_manager_update_pkg

  • Click the Update button

Terminal Window or Python Command Prompt

Activate the environment containing the arcgis package and type:

conda upgrade -c esri arcgis

ArcGIS Pro 1.3

ArcGIS Pro 1.3 will install the ArcGIS API for Python 1.0 (the arcgis 1.0 package) release. To upgrade the arcgis package you would have to install a later release of ArcGIS Pro.


Using the API

Start the Jupyter notebook installed with the API:

Windows:

  • Navigate to Start Menu > All Programs > ArcGIS > Python Command Prompt
  • Change to a directory with notebooks in it, or one where you want to create notebooks
  • Enter the following at the prompt to start jupyter:
    jupyter notebook
    
  • Proceed to Test your install with jupyter notebook

macOS and Linux:

  • Open a terminal application
  • Change to a directory with notebooks in it, or one where you want to create notebooks
  • Enter the following at the prompt to start jupyter:
    jupyter notebook
    
  • Proceed to Test your install with jupyter notebook

The Jupyter dashboard opens in a web browser. For instructions on using the Jupyter Notebook, refer to the how to use the notebook environment guide.


Test your install with jupyter notebook

From the Jupyter Notebook dashboard:

  • Windows:  Click New > Python 3
  • macOS and Linux:  Click New > Python[default]

Enter the following lines of code:

from arcgis.gis import GIS
my_gis = GIS()
my_gis.map()

You should see a map come up as shown below:

test your install

Learn more about the API using the guide and try out the samples.


Install as a Docker image

Docker is a popular containerization technology. Docker containers bundle software in a complete file system with everything that is needed to run it. Docker containers run the same regardless of your operating system. To learn more about docker, refer to the official documentation.

The ArcGIS API for Python is shipped as a Docker image which you can download and power up whenever you want to use the API. These images when spun up into containers, run in an isolated environment without making any changes to your local file system.

Follow the steps below to get Docker on your computer and run the API:

  • Download docker and install it on your computer.
  • Once installed, run the following command in terminal to pull Docker image

    docker pull esridocker/arcgis-api-python-notebook

    docker pull command

  • Then spin the image into a container using the following command in terminal. Replace the <localport> with an available port number, for instance 8889.

    docker run -it -p <localport>:8888 esridocker/arcgis-api-python-notebook

  • When the container starts, it will provide a URL (with a one time token) to open your local Notebook instance. Copy the URL and paste it in your browser's address bar to use the notebooks.

Install-Offline

Install the API on a machine without internet access or on a disconnected network with the following steps:

  • Install the latest version of full Anaconda for Python 3x for your OS
  • Download the latest version of the ArcGIS API for Python appropriate for your OS from Esri's channel on anaconda.org
    • For instance, if you are installing on Linux 64-bit, download linux-64/arcgis-1.0.1-py36_1.tar.bz2 package
  • Open your terminal application and install the API
    conda install /path_to_package_download_folder/linux-64/arcgis-1.0.1-py36_1.tar.bz2
    

To use the API in different IDEs, proceed to Using the API



NOTE: For advanced users or those needing information on specific environments, see Configuration for options to configure various aspects of conda


Feedback on this topic?