You should have conda and the ArcGIS API for Python installed on your system. If you don't, please see the Install and set up guide for instructions.
Let's talk about some basics of conda so you can manage installations and set up IDEs for projects and scripts. Whether installed manually or as part of another software installation (as is the case with ArcGIS Pro), conda can be installed in one of 2 varieties:
- Full Anaconda Distribution - installs conda and hundreds of additional Python packages
- Miniconda - installs only Python, conda and other libraries needed to run conda
See Anaconda or Miniconda for an explanation of differences.
The Conda Basics
The easiest way to understand conda is by working through the 30-minute Getting Started tutorial. The sections below summarize and outline the commands you need to know to work with the ArcGIS API for Python.
Conda is a platform-independent package manager application that can install, update, and remove Python packages. Packages are bundles of software and supporting files stored in any of a variety of repositories called channels. Channels may be a default set of cloud locations, such as Anaconda Cloud, or private repositories created by individuals or organizations. Conda searches a default set of channels when listing or installing packages. See Conda channels for more information, such as how to configure conda to search specific channels.
Esri has created a conda repository at a channel named esri to store the arcgis package. You can access channels with a flag in the conda install command, and instruct conda to install packages into specific conda environments. The rest of this document provides basic instructions to work with conda environments and links to resources providing more details.
Conda Environments
When you create conda environments, you create physical directories that isolate the specific Python interpreter and packages you install into the environment. This allows you to create multiple environments that can have different versions of software, including Python. You can easily create new environments and then switch between them without affecting other environments. For detailed explanation and instructions, see the conda documentation on Managing environments.
Let's explore what is available directly after installing conda through either ArcGIS Pro or the Anaconda Distribution.
ArcGIS Pro
After the installation of ArcGIS Pro, the bundled conda will have 2 conda environments on your system:
base
This environment contains an installation of Miniconda, a smaller version of Anaconda that includes conda, Python, the packages they depend on, as well as a select set of useful packages.
arcgispro-py3
This environment contains Python and the arcgispro package, including all the ArcPy functionality.
Manage conda environments with ArcGIS Pro:
You can use 3 different methods to maintain your conda environments. Each provides methods to install, update and remove packages:
A GUI tool accessible from the ArcGIS Pro Project tab.
A command-line shortcut that opens in the arcgispro-py3 directory and activates the environment. You can open this by searching Python Command Prompt in the windows start menu.
The standard MS-DOS Windows command-line application.
NOTE: For additional technical information about conda and ArcGIS Pro, see these articles:
- Python and ArcGIS Pro 1.3: Conda
- Conda and ArcGIS Pro 1.4
- ArcGIS Notebooks in ArcGIS Pro (2.9) FAQ
- ArcGIS Notebooks in ArcGIS Pro (3.0) FAQ
Anaconda Distribution
After the installation, Anaconda installs Python, conda, and hundreds of default packages into one environment:
base
Manage conda environments with Anaconda:
You can use a couple different applications to manage your conda environments:
- Terminal Application
Standard command-line terminal applications on either the Windows, macOS, or Linux operating systems.
A GUI application to comprehensively maintain conda enviroments.
Activating Environments
There can be multiple environments in conda. To use an environment, you must activate it. The activate command switches between environments at a terminal application. See Activating an environment for more information:
-
Windows:
`activate <environment_name>` -
macOS and Linux:
source activate <environment_name>
Once activated, type python in a terminal to access the Python interpreter for that environment instead of the global Python interpreter.
Adding Packages to Environments
You can add a package to the currently active environment at the terminal with the following command:
conda install <package_name>
You can also specify specific environments and channels with the --name and --channel flags:
conda install --name <environment_name> --channel <channel_name> <package_name>
See Managing packages for detailed instructions on using the conda command-line interface. See the The Default Environments section for detailed instructions on using ArcGIS Pro or Anaconda tools.
Setting up IDEs
To begin projects in IDEs, you often have to specify the path to the Python interpreter. When using conda environments, each environment you create uses a different Python interpreter. Here there can be two cases:
-
If using the ArcGis Pro bundled conda environment, open Python Command Prompt by searching it in the start menu and use the below mentioned command.
-
If you are using Anaconda then open Anaconda Command Prompt by searching it in start menu and use the below mentioned command.
Type the following to get a list of all environments on your machine and the directory location of the specific Python interpreter (python.exe) used for that environment:
conda info --envs
Enter the directory name and add python.exe to set the correct path to the Python interpreter for a specific environment. For example, the correct interpreter for the arcgispro-py3 environment in an IDE based on the screenshot above would be:
C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe
See Finding your Anaconda Python interpreter path for more detailed instructions on different systems.
Step by Step on macOS: A GIS Environment
Let's tie all these concepts together. The following steps create an environment, install the ArcGIS API for Python, activate the environment and start a Jupyter Notebook IDE from that environment:
Create an environment:
conda create --name gis-enviro
You can name your environment anything you want.
Install the ArcGIS API for Python¶
conda install --name gis-enviro -c esri arcgis
If you do not enter an environment name, the package will be installed in the active environment.
Activate the environment
source activate gis-enviro
The ArcGIS API for Python integrates with the Jupyter Notebook. Jupyter Documentation has more information about the suite of software and tools.
Start the Jupyter Notebook
Navigate to the directory where you want to create notebooks (or where notebooks already exist).
jupyter notebook
If installed correctly, you'll see a message indicating that a web server has started. Your default web browser will launch from your current directory. Full documentation including samples and an API Reference located at https://developers.arcgis.com/python.