![](https://anaconda.org/conda-forge/earthengine-api/badges/version.svg) ![](https://anaconda.org/conda-forge/earthengine-api/badges/latest_release_date.svg) The Earth Engine Python API can be installed to a local machine via [conda](https://docs.conda.io/projects/conda/en/latest/#), a Python package and environment manager. Conda is bundled with [Anaconda](https://www.anaconda.com/distribution/) and [Miniconda](https://docs.conda.io/projects/conda/en/latest/glossary.html#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] > **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](https://developers.google.com/earth-engine/guides/python_install-conda#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](https://developers.google.com/earth-engine/guides/python_install-conda#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](https://developers.google.com/earth-engine/guides/python_install-conda#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](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) and [Anaconda Installation](https://docs.anaconda.com/anaconda/install/) pages. ## Install conda > [!NOTE] > **Note:** Skip to the [Install API](https://developers.google.com/earth-engine/guides/python_install-conda#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](https://www.anaconda.com/distribution/) and then skip to the [Install API](https://developers.google.com/earth-engine/guides/python_install-conda#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] > **Note:** An activated conda environment can be deactivated by running: `conda deactivate`. > [!NOTE] > **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] > **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] > **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] > **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] > **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] > **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: . 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](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html). > [!NOTE] > **Note:** The following first step assumes you have just completed the [Install conda](https://developers.google.com/earth-engine/guides/python_install-conda#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](https://developers.google.com/earth-engine/command_line). ## 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 ```python import ee # Initialize the Earth Engine module. ee.Initialize() # Print metadata for a DEM dataset. print(ee.Image('NASA/NASADEM_HGT/001').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](https://developers.google.com/earth-engine/guides/python_install-conda#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](https://developers.google.com/earth-engine/guides/python_install-conda#add_miniconda_to_path_variable) 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](https://developers.google.com/earth-engine/guides/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. ```python 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] > **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] > **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.