Python Installation - Conda Install

The Earth Engine Python API can be installed to a local machine via conda, a Python package and environment manager. Conda is bundled with Anaconda and Miniconda Python distributions. Anaconda is a data science programming platform that includes 1500+ packages, while Miniconda includes only conda and its dependencies. Either of these Python distributions are suitable for installing and working with the Earth Engine API. If you're unfamiliar with these distributions, please visit their links to learn more.

This guide will direct you through:

• Checking for an existing conda install
• Installing conda on a local machine
• Installing the Earth Engine Python API
• Setting up authentication credentials
• Testing the API

Note: The following steps will be completed in either a Windows command prompt or Unix terminal (Linux/Mac). Use the tabs at the top of each code section to switch to commands relevant to your operating system.

Check for conda install

If conda is already installed on your system, skip to the Install API section. If you are unsure whether conda is installed, verify by entering the following command at your command line interface.

conda --help

If conda is installed and its system path is registered in the PATH environmental variable, conda help contents should appear in the terminal. If the help contents appear, skip to the Install API section. If conda is not recognized, the result will read something like: conda not found or not recognized as a command. It is possible that the program exists on your system but is not registered in the PATH environmental variable. Even if this is the case, for consistency, please continue with the Install conda section, as it is difficult to address all possible system configurations. As long as the folder 'miniconda3' does not exist in your Home folder, the following conda install instructions should succeed. For more information on conda install location and registration, please see the Miniconda Installation and Anaconda Installation pages.

Install conda

Note: Skip to the Install API section if conda is already installed on your system.

In this section you will download and install Miniconda, which will serve as the Python platform to access the Earth Engine API. As described above, you may use Miniconda or Anaconda, but to minimize impact to your system, this guide will describe a Miniconda installation with no alteration to your system's environmental variables. If you prefer Anaconda, please see the installation instructions provided here and then skip to the Install API section.

Install Miniconda

Downloading and installing Miniconda is accomplished in three steps:

1. Download the 64-bit Python 3 Miniconda installer to your Home directory
2. Run the installer
3. Delete the installer

Complete these steps by copying and pasting the following lines into the appropriate command line interface for your system. Installation results in a folder named 'miniconda3' added to your Home directory.

1. Download the Miniconda installer to your Home directory.

Linux

wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh

Mac

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o ~/miniconda.sh

Windows

powershell -command "Invoke-WebRequest -Uri https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -OutFile ~\miniconda.exe"

2. Install Miniconda quietly, accepting defaults, to your Home directory.

Linux

bash ~/miniconda.sh -b

Mac

bash ~/miniconda.sh -b

Windows

start /B /WAIT %UserProfile%\miniconda.exe /InstallationType=JustMe /AddToPath=0 /RegisterPython=0 /S /D=%UserProfile%\miniconda3

3. Remove the Miniconda installer from your Home directory.

Linux

rm ~/miniconda.sh

Mac

rm ~/miniconda.sh

Windows

del %UserProfile%\miniconda.exe

Test Miniconda install

Print the conda command's help menu to test the Miniconda install. Since Miniconda has not been added to your system's PATH environment variable, you will first need to activate conda for this session by calling the activate command by its full system path. A successful test will result in conda help contents appearing in the terminal. Run the following lines in your system's command line interface.

Linux

source $HOME/miniconda3/bin/activate
conda --help

Mac

source $HOME/miniconda3/bin/activate
conda --help

Windows

%UserProfile%\miniconda3\condabin\activate
conda --help

Note: An activated conda environment can be deactivated by running: conda deactivate.

Note: If the path to Miniconda is not set as an environmental variable, as in this case of this install, you need to activate Miniconda for every new command line session in the future, including use of the API. Use the first command from the above code snippet to activate Miniconda as needed.

Add Miniconda to PATH variable

Caution: Altering your system's PATH variable can have unintended consequences.

You can optionally add the Miniconda installation path to your system's PATH variable, which will allow you to interact with conda by a simple call to conda without having to first run the activate command by its full path. The following instructions walk through adding the Miniconda install to your system's PATH variable.

Linux

Add the following path to your 'PATH' environmental variable by completing either the GUI or command line instructions below.

$HOME/miniconda3/bin

GUI

1. Open the .bashrc file found in your $HOME directory in a text editor.

xdg-open ~/.bashrc

2. Copy and paste the following lines to the bottom of the file.

# add path to conda
export PATH="$HOME/miniconda3/bin:$PATH"

3. Save the file and close the text editor.

Note: The added conda path can be removed by deleting the lines just added.

Command line

Enter the following command in a terminal to append the conda path to the ~/.bashrc file.

printf '\n# add path to conda\nexport PATH="$HOME/miniconda3/bin:$PATH"\n' >> ~/.bashrc

Mac

Add the following path to your 'PATH' environmental variable by completing either the GUI or command line instructions below.

$HOME/miniconda3/bin

GUI

1. Open the .bashrc file found in your $HOME directory in a text editor.

touch ~/.bashrc; open -t ~/.bashrc

2. Copy and paste the following lines to the bottom of the file.

# add path to conda
export PATH="$HOME/miniconda3/bin:$PATH"

3. Save the file and close the text editor.

Note: The added conda path can be removed by deleting the lines just added.

Command line

Enter the following command in a terminal to append the conda path to the ~/.bashrc file.

printf '\n# add path to conda\nexport PATH="$HOME/miniconda3/bin:$PATH"\n' >> ~/.bashrc

Windows

Add the following path to your 'Path' environmental variable by completing either the GUI or command line instructions below.

%UserProfile%\miniconda3\condabin

GUI

1. Enter the following line in a command prompt to open the 'Environmental Variable' dialog.

rundll32 sysdm.cpl,EditEnvironmentVariables

2. Double-click the 'Path' variable under the 'User' section to select it for editing.

3. Click the 'Edit text' button in the new 'Edit' dialog window to open the editor.

4. Add the following string to the end of the existing 'Path' variable value. Ensure that semicolons (;) surround the entry to distinguish it from neighboring entries.

%UserProfile%\miniconda3\condabin;

5. Click 'Okay' buttons until all dialog windows are closed.

Note: The added conda path can be removed following the same editing method.

Command line

Use the setx command to append the path. From a command prompt enter:

setx Path "%Path%%UserProfile%\miniconda3\condabin;"

Note: Restart open command line interfaces for environmental variable changes to take effect.

Initialize conda

Initialize conda for shell interaction. Run the proceeding command for information on initialization for various shells. Follow subsequent instructions printed to the console upon entering the command.

conda init --help

After restarting your command line interface, you should be able to activate the base conda environment with the following command.

conda activate

Install API

The Earth Engine Python API is distributed as a conda-forge package at: https://anaconda.org/conda-forge/earthengine-api. It is installed with the conda install command. Before installing, however, make a conda environment specifically for Earth Engine. Installing the Earth Engine API to its own environment ensures that it and its dependent packages will not cause versioning issues with your base environment or any other environment you've previously set up and vice versa. For more information on managing conda environments, please visit this site.

Note: The following first step assumes you have just completed the Install conda section without altering environmental variables or initializing conda for shell use; the command is structured accordingly. If you have previously installed conda by another means or have registered conda for use in the shell, please do what is necessary to activate conda, then begin following instructions with step 2.

1. Activate your base conda environment, if it is not already.

Linux

source $HOME/miniconda3/bin/activate

Mac

source $HOME/miniconda3/bin/activate

Windows

%UserProfile%\miniconda3\condabin\activate

2. Make a conda virtual environment for the Earth Engine API.

conda create --name ee

You will be asked to confirm creation of the environment, do so.

3. Activate the conda ee environment.

conda activate ee

4. Install the API into the conda ee environment. Ensure that (ee) appears at the beginning of the command line, indicating you are working from the ee environment.

conda install -c conda-forge earthengine-api

You will be asked to confirm the installation of the API and its dependencies. After confirming, conda will download and install the dependencies. If all goes well, you will now have a conda environment called 'ee' with all the requirements for accessing the API, as well as the earthengine command line tool.

Get credentials

Before using the Earth Engine API or earthengine command line tool, you must perform a one-time authentication that authorizes access to Earth Engine on behalf of your Google account. To authenticate, use the authenticate command from the earthengine command line tool.

Within your conda ee environment run the following command and follow the resulting printed instructions. A URL will be provided that generates an authorization code upon agreement. Copy the authorization code and enter it as command line input.

earthengine authenticate

Upon entering the authorization code, an authorization token gets saved to a credentials file which can be found below. Subsequent use of the API's ee.Initialize() command and the earthengine command line tool will look to this file to authenticate. If you want to revoke authorization, simply delete the credentials file.

Linux

ls $HOME/.config/earthengine/credentials

Mac

ls $HOME/.config/earthengine/credentials

Windows

dir %UserProfile%\.config\earthengine\credentials

Testing the API

Run a simple Python script that prints metadata for a DEM dataset to test the API installation. It should print a JSON object to the console.

1. Start a python interpreter from your conda ee environment.

python

2. Run the following Python lines one-by-one to print the metadata for a DEM dataset

import ee

# Initialize the Earth Engine module.
ee.Initialize()

# Print metadata for a DEM dataset.
print(ee.Image('USGS/SRTMGL1_003').getInfo())

Subsequent API use

Anytime you wish to use the Earth Engine API you must first activate your conda ee environment. The activation procedure depends on whether conda is registered for use in the shell or not. Follow the instructions relevant to your conda install below.

Conda not registered

The following conda ee environment activation command assumes that conda has been installed following the instructions in the above Install conda section i.e. the install path is assumed based on prior steps. Run the following command in a command line interface.

Linux

source $HOME/miniconda3/bin/activate ee

Mac

source $HOME/miniconda3/bin/activate ee

Windows

%UserProfile%\miniconda3\condabin\activate ee

Conda registered

The following conda ee environment activation command assumes that conda has been registered for use in the shell or command prompt by instructions in this guide or by other means. Run the following command in a command line interface.

conda activate ee

After running the command, you should see (ee) at the beginning of the command line, indicating that you are working from the ee environment.

You are now ready to start a Python interpreter and access the Earth Engine Python API. Please refer to the Python Install page for general guidance on working with the Python API.

Updating the API

Use the conda update command to update your ee environment to the latest API version. Remember to first activate your conda ee environment, if it is not already active.

conda update -c conda-forge earthengine-api

Get the currently installed version number in Python by printing the ee library __version__ property. Start a Python interpreter by entering python in the ee conda environment command line and then enter the following commands.

import ee
print(ee.__version__)

Sharing your ee environment

It can be helpful to share your conda Python environment with others to achieve reproducible and replicable results, particularly when you have installed additional Python packages. Conda provides a convenient way for others to replicate your environment.

From your conda ee environment, run the following command to save a YAML file called 'ee-shared-env' to your Home directory, which lists your environment specifications.

Linux

conda env export > $HOME/ee-shared-env.yml

Mac

conda env export > $HOME/ee-shared-env.yml

Windows

conda env export > %UserProfile%\ee-shared-env.yml

Share the resulting file, and the recipient can replicate the environment by running the following conda command.

conda env create -f path-to-ee-shared-env.yml

Note: The first line of the ee-shared-env.yml file defines the name of the environment to be created. Conda will not overwrite an existing environment, so the name of the environment in the ee-shared-env.yml file may need to be altered. Alternatively, use conda's remove command or the --clone flag of conda's create command to manage environment names.

Note: Replicating environments across operating systems may fail, as there are OS-specific package builds and versions that may not be available or create dependency conflicts.