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

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

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.

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

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

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.

bash ~/miniconda.sh -b

bash ~/miniconda.sh -b

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.

rm ~/miniconda.sh

rm ~/miniconda.sh

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.

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

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

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

Add Miniconda to PATH variable

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.

xdg-open ~/.bashrc

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

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

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

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

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

rundll32 sysdm.cpl,EditEnvironmentVariables

%UserProfile%\miniconda3\condabin;

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

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.

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

source $HOME/miniconda3/bin/activate

source $HOME/miniconda3/bin/activate

%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.

ls $HOME/.config/earthengine/credentials

ls $HOME/.config/earthengine/credentials

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.

source $HOME/miniconda3/bin/activate ee

source $HOME/miniconda3/bin/activate ee

%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.

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

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

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