Python installation

Install options

The Earth Engine Python API is available as a Python package that can be installed locally or accessed through a Google Colab Notebook.

Colab icon Run in Google Colab Local conda install

See alternative pip install instructions

Install the API to an arbitrary Python environment using pip. From a terminal or command prompt:

pip install earthengine-api

Once installed, you can import, authenticate and initialize as described here.

Update the API:

pip install earthengine-api --upgrade

Syntax

Both the Python and JavaScript APIs access the same server-side functionality, but client-side expressions (learn more about client vs. server) can vary because of language syntax differences. The following table and code block includes a list of the common syntax differences you'll encounter when working with the Python API relative to the JavaScript API.

Common syntax differences between JavaScript and Python
Property JavaScript Python
Function definition function myFun() {}
...or...
var myFun = function() {}
def my_fun():
Anonymous function mapping map(function(x) {
  return x
})
map(lambda x: x)
Variable definition var myVar = "var" my_var = "var"
Logical operators and()
or()
not()
And()
Or()
Not()
Multi-line method chain myReally()
  .reallyLong()
  .methodChain()
(myReally()
 .reallyLong()
 .methodChain())
Dictionary keys {"key": "value"}
...or...
{key: "value"}
{"key": "value"}
Dictionary object access dictionary.key
...or...
dictionary["key"]
dictionary["key"]
Function argument definition In order or by dictionary key-value pairs In order, by name, or dictionary key-value pairs
Boolean true
false
True
False
Null values null None
comment // #

A demonstration of JavaScript and Python syntax differences:

JavaScript

// Define a function
function myFun(img) {
  return img;
}

var myFun = function(img) {
  return img;
};

// Anonymous function mapping
var result = collection.map(function(img) {
  return img;
});

// Define a variable
var myVar = "var";

// Logical operators
var match = this.and(that);
var match = this.or(that);
var match = this.not(that);

// Multi-line method chain
var foo = myReally()
  .reallyLong()
  .methodChain();

// Dictionary keys
var dictionary = {"key": value};
var dictionary = {key: value};

// Dictionary object access
var value = dictionary.key;
var value = dictionary["key"];

// Function argument definition
var img = myFun(arg1, arg2, arg3); // in order, unbroken
var img = myFun({arg1:arg1, arg3:arg3}); // dictionary key-value pairs

// Boolean
var t = true;
var f = false;

// Null values
var na = null;

Python

# Define a function
def my_fun(img):
    return img

# Anonymous function mapping
result = collection.map(lambda img: img)

# Define a variable
my_var = "var"

# Logical operators
match = this.And(that)
match = this.Or(that)
match = this.Not(that)

# Multi-line method chain
foo = (myReally()
       .reallyLong()
       .methodChain())

# Dictionary keys
dictionary = {"key": value}

# Dictionary object access
value = dictionary["key"]

# Function argument definition
img = my_fun(arg1, arg2, arg3)  # in order, unbroken
img = my_fun({"arg1": arg1, "arg3": arg3})  # dictionary key-value pairs
img = my_fun(arg2=arg2, arg3=arg3)  # by parameter name

# Boolean
t = True
f = False

# Null values
na = None

Package import

The Python API package is called ee. It must be imported into every new Python session and script:

import ee

Authenticate to Earth Engine servers:

ee.Authenticate()

Initialize the API for every new session and script:

ee.Initialize()

Exporting data

Exporting data with the Python API requires the use of the ee.batch module, which accepts arguments differently than the JavaScript Export module. Specifically, it does not accept an argument dictionary and the region parameter cannot be an ee.Geometry object. Use named arguments to set parameters. The region parameter needs to be the coordinates member of a GeoJSON object. See the GeoJSON Polygon spec and/or this example for details. Additionally, export tasks must be started by calling the start() method on a defined export task. Started task status can be queried by calling the status() method on the task.

Create an export task:

task = ee.batch.Export.image.toDrive(image=my_img,
                                     region=my_geometry.getInfo()['coordinates'],
                                     description='my_description',
                                     folder='my_gdrive_folder',
                                     fileNamePrefix='my_file_prefix',
                                     scale=my_scale,
                                     crs=my_crs)

Start an export task:

task.start()

Check export task status:

task.status()

Printing objects

Printing an Earth Engine object in Python prints the serialized request for the object, not the object itself. Refer to the Client vs. server page to understand the reason for this.

Call getInfo() on Earth Engine objects to get the desired object from the server to the client:

# Load a Landsat image.
img = ee.Image('LANDSAT/LT05/C01/T1_SR/LT05_034033_20000913')

# Print image object WITHOUT call to getInfo(); prints serialized request instructions.
print(img)

# Print image object WITH call to getInfo(); prints image metadata.
print(img.getInfo())
Note that getInfo() is a synchronous operation, meaning execution of expressions following the getInfo() call are blocked until the result is returned to the client. Additionally, requests for a lot of data or expensive computations can return an error and/or hang. In general, the best practice is to export your results, and once complete, import them into a new script for further analysis.

UI objects

The Earth Engine ui module is only available through the JavaScript API Code Editor. Use third party libraries for UI elements in Python. Folium and ipyleaflet provide interactive map handling, while charting can be done with Matplotlib, Altair, or seaborn, to name a few. See examples in the Earth Engine in Colab setup notebook.