Announcement: On November 13, 2024, all users will need to use a Cloud project in order to access Earth Engine. After this date, continued individual access without a Cloud project will require an exception.

Python Installation - Colab Notebook

The Earth Engine Python API can be deployed in a Google Colaboratory notebook. Colab notebooks are Jupyter notebooks that run in the cloud and are highly integrated with Google Drive, making them easy to set up, access, and share. If you are unfamiliar with Google Colab or Jupyter notebooks, please spend some time exploring the Colab welcome site.

The following sections describe deploying Earth Engine in Google Colab and visualizing maps and charts using third‑party Python packages.

Open a Colab notebook

Notebooks can be opened from either Google Drive or the Colaboratory interface.

New notebook

Google Drive

Open Google Drive and create a new file.

New > More > Colaboratory
Right click in a folder and select More > Colaboratory from the context menu.

Colab interface

Visit the Colab site and create a new file.

File > New > New Python 3 notebook
If you have interacted with Colab previously, visiting the above linked site will provide you with a file explorer where you can start a new file using the dropdown menu at the bottom of the window.

Existing notebook

Existing notebook files (.ipynb) can be opened from Google Drive and the Colab interface.

Google Drive

Colab notebooks can exist in various folders in Google Drive depending on where notebooks files were created. Notebooks created in Google Drive will exist in the folder they were created or moved to. Notebooks created from the Colab interface will default to a folder called 'Colab Notebooks' which is automatically added to the 'My Drive' folder of your Google Drive when you start working with Colab.

Colab files can be identified by a yellow 'CO' symbol and '.ipynb' file extension. Open files by either doubling clicking on them and selecting Open with > Colaboratory from the button found at the top of the resulting page or by right clicking on a file and selecting Open with > Colaboratory from the file's context menu.

Colab interface

Opening notebooks from the Colab interface allows you to access existing files from Google Drive, GitHub, and local hardware. Visiting the Colab interface after initial use will result in a file explorer modal appearing. From the tabs at the top of the file explorer, select a source and navigate to the .ipynb file you wish to open. The file explorer can also be accessed from the Colab interface by selecting File > Open notebook or using the Ctrl+O keyboard combination.

Import API and get credentials

This section demonstrates how to import the Earth Engine Python API and authenticate access. This content is also available as a Colab notebook:

Run in Google Colab

View source on GitHub

The Earth Engine API is included by default in Google Colaboratory so requires only importing and authenticating. These steps must be completed for each new Colab session or if you restart your Colab kernel or if your Colab virtual machine is recycled due to inactivity.

Import the API

Run the following cell to import the API into your session.

import ee

Authenticate and initialize

Run the ee.Authenticate function to authenticate your access to Earth Engine servers and ee.Initialize to initialize it. Add a code cell, enter the following lines, edit the project, and run the cell.

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the library.
ee.Initialize(project='my-project')

You'll be asked to authorize access to your Earth Engine account. Follow the instructions printed to the cell to complete this step.

Test the API

Test the API by printing the elevation of Mount Everest. Note that before using the API you must initialize it. Run the following Python script in a new cell.

# Print the elevation of Mount Everest.
dem = ee.Image('USGS/SRTMGL1_003')
xy = ee.Geometry.Point([86.9250, 27.9881])
elev = dem.sample(xy, 30).first().get('elevation').getInfo()
print('Mount Everest elevation (m):', elev)

Map visualization

ee.Image objects can be displayed to notebook output cells. The following two examples demonstrate displaying a static image and an interactive map.

Static image

The IPython.display module contains the Image function, which can display the results of a URL representing an image generated from a call to the Earth Engine getThumbUrl function. The following script will display a thumbnail of a global elevation model.

# Import libraries.
import ee
from IPython.display import Image

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the library.
ee.Initialize(project='my-project')

# Import a DEM and display a thumbnail of it.
dem = ee.Image('USGS/SRTMGL1_003')
Image(url=dem.updateMask(dem.gt(0))
  .getThumbUrl({'min': 0, 'max': 4000, 'dimensions': 512,
                'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5']}))

Interactive map

The folium package can be used to display ee.Image objects on an interactive Leaflet map. Folium has no default method for handling tiles from Earth Engine, so one must be defined and added to the folium.Map module before use.

The following script provides an example of adding a method for handing Earth Engine tiles and using it to display an elevation model to a Leaflet map.

# Import libraries.
import ee
import folium

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the library.
ee.Initialize(project='my-project')

# Define a method for displaying Earth Engine image tiles to folium map.
def add_ee_layer(self, ee_image_object, vis_params, name):
  map_id_dict = ee.Image(ee_image_object).getMapId(vis_params)
  folium.raster_layers.TileLayer(
    tiles = map_id_dict['tile_fetcher'].url_format,
    attr = "Map Data © Google Earth Engine",
    name = name,
    overlay = True,
    control = True
  ).add_to(self)

# Add EE drawing method to folium.
folium.Map.add_ee_layer = add_ee_layer

# Fetch an elevation model.
dem = ee.Image('USGS/SRTMGL1_003')
# Set visualization parameters.
vis_params = {
  'min': 0,
  'max': 4000,
  'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5']}

# Create a folium map object.
my_map = folium.Map(location=[20, 0], zoom_start=3)

# Add the elevation model to the map object.
my_map.add_ee_layer(dem.updateMask(dem.gt(0)), vis_params, 'DEM')

# Add a layer control panel to the map.
my_map.add_child(folium.LayerControl())

# Display the map.
display(my_map)

Chart visualization

Some Earth Engine functions produce tabular data that can be plotted by data visualization packages such as matplotlib. The following example demonstrates the display of tabular data from Earth Engine as a scatter plot. See Charting in Colaboratory for more information.

# Import libraries.
import ee
import matplotlib.pyplot as plt

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the Earth Engine module.
ee.Initialize(project='my-project')

# Fetch a Landsat TOA image.
img = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_034033_20000913')

# Select Red and NIR bands, scale them, and sample 500 points.
samp_fc = img.select(['B3','B4']).sample(scale=30, numPixels=500)

# Arrange the sample as a list of lists.
samp_dict = samp_fc.reduceColumns(ee.Reducer.toList().repeat(2), ['B3', 'B4'])
samp_list = ee.List(samp_dict.get('list'))

# Save server-side ee.List as a client-side Python list.
samp_data = samp_list.getInfo()

# Display a scatter plot of Red-NIR sample pairs using matplotlib.
plt.scatter(samp_data[0], samp_data[1], alpha=0.2)
plt.xlabel('Red', fontsize=12)
plt.ylabel('NIR', fontsize=12)
plt.show()