Installation

Install Xee with pip or conda. Use virtual environments (venv, conda envs) to avoid dependency conflicts.

Xee v0.1.0 introduced a refactored API with breaking changes relative to the 0.0.x series. This page documents the v0.1.0+ install and usage path. If you are upgrading from 0.0.x, review the Migration Guide.

Install

Install from pip:

pip install --upgrade xee

Install from conda-forge:

conda install -c conda-forge xee

Prerelease versions

Before each stable release, Xee publishes one or more release candidates (e.g. v0.1.1rc1) to PyPI. If you want to test upcoming changes before the stable release:

pip install --upgrade --pre xee

Or pin a specific release candidate:

pip install xee==0.1.1rc1

Prerelease builds are not published to Conda-Forge.

Earth Engine setup

Xee makes requests to Google Earth Engine for data. To use Earth Engine, you’ll need to create and register a Google Cloud project, authenticate with Google, and initialize the service.

If you already have a registered Earth Engine Cloud project and know the auth/initialize steps, skip to the Quickstart.

Note: the authentication and initialization steps described in the following sections cover the majority of common system configurations and access methods, if you’re having trouble, refer to the Earth Engine Authentication and Initialization guide.

1. Create and register a Cloud project

Follow instructions in the Earth Engine Access guide to create and register a Google Cloud project.

2. Authentication

Google needs to know who is accessing Earth Engine to determine what services are available and what permissions are granted. The goal of authentication is to establish credentials that can be used during initialization. There are several ways to verify your identity and create credentials, depending on your working environment:

Persistent environment (one-time)

If you’re working from a system with a persistent environment, such as a local computer or on-premises server, you can authenticate using the Earth Engine command line utility:

earthengine authenticate

This command opens a browser window for authentication. Once authenticated, the credentials are stored locally (~/.config/earthengine/credentials), allowing them to be used in subsequent initialization to the Earth Engine service. This is typically a one-time step.

Ephemeral environment (each session)

If you’re working from a system like Google Colab that provides a temporary environment recycled after use, you’ll need to authenticate every session. In this case, you can use the earthengine-api library (installed with Xee) to authenticate interactively:

ee.Authenticate()

This method selects the most appropriate authentication mode and guides you through steps to generate authentication credentials. Be sure to rerun the authentication process each time the environment is reset.

3. Initialization

Initialization checks user authentication credentials, sets the Cloud project to use for requests, and connects the client to Earth Engine’s services. At the top of your script, include one of the following expressions with the project argument modified to match the Google Cloud project ID enabled and registered for Earth Engine use.

High-volume endpoint (stored collections)

If you are requesting stored data (supplying a collection ID or passing an unmodified ee.ImageCollection() object to xarray.open_dataset), connect to the high-volume endpoint.

ee.Initialize(
    project='your-project-id',
    opt_url='https://earthengine-highvolume.googleapis.com'
)

Standard endpoint (computed collections / iterative development)

If you are requesting computed data (applying expressions to the data), consider connecting to the standard endpoint. It utilizes caching, so it can be more efficient if you need to rerun or adjust something about the request.

 ee.Initialize(project='your-project-id')

For more tuning guidance, see Performance & Limits.