Quickstart

Get up and running with Xee in a few minutes.

1. Install

pip install --upgrade xee

Optional (plotting): pip install matplotlib. For full installation options, see Installation.

2. Earth Engine access

You need an Earth Engine–enabled Google Cloud project. If you haven’t done this yet, follow the Earth Engine Access guide.

Authenticate once on a persistent machine:

earthengine authenticate

Or inside ephemeral environments (e.g. Colab):

import ee
ee.Authenticate()

Initialize (high-volume endpoint recommended for reading stored collections):

import ee
ee.Initialize(
    project='YOUR-PROJECT-ID',
    opt_url='https://earthengine-highvolume.googleapis.com'
)

For computed collections (server-side expressions), omit opt_url to use the standard endpoint, which benefits from caching during iterative development.

3. Open your first dataset

import ee, xarray as xr
from xee import helpers

ic = ee.ImageCollection('ECMWF/ERA5_LAND/MONTHLY_AGGR')
grid = helpers.extract_grid_params(ic)  # match source projection & resolution
ds = xr.open_dataset(ic, engine='ee', **grid)
print(ds)

Choosing a grid strategy quickly

  • Exploratory analysis: use helpers.extract_grid_params(...).

  • Fixed output shape (for model inputs): use helpers.fit_geometry(..., grid_shape=...).

  • Fixed physical resolution: use helpers.fit_geometry(..., grid_scale=...).

  • Manual crs / crs_transform / shape_2d: advanced alignment workflows only.

Dataset ID input forms

Xee accepts both plain Earth Engine asset IDs (for example, ECMWF/ERA5_LAND/MONTHLY_AGGR) and URI forms (for example, ee://ECMWF/ERA5_LAND/MONTHLY_AGGR).

Where do these parameters come from?

xr.open_dataset(..., engine='ee') is the primary user entrypoint for Xee. For the complete, canonical parameter reference (including defaults and backend behavior), see Open Dataset Reference.

Plot the first time slice (matplotlib required):

ds['temperature_2m'].isel(time=0).plot()

4. Next steps

Goal

Where to go

Learn grid parameter patterns

Concepts

Fit a custom area or scale

User Guide

API signatures

API Reference

Migrate 0.0.x code

Migration Guide

Performance tips

Performance & Limits

Troubleshooting common issues

FAQ

5. Minimal workflow recap

  1. Install Xee & authenticate EE

  2. Initialize EE client

  3. Derive grid parameters (match source or fit a geometry)

  4. Call xr.open_dataset(..., engine='ee', **grid)

  5. Use Xarray normally (select, compute, visualize, export)

6. Example: custom AOI at fixed size

AOI means area of interest.

import shapely
from xee import helpers

aoi = shapely.geometry.box(113.33, -43.63, 153.56, -10.66)  # Australia
grid = helpers.fit_geometry(
    geometry=aoi,
    grid_crs='EPSG:4326',   # degrees
    grid_shape=(256, 256)   # (width, height) pixels
)

ds = xr.open_dataset('ee://ECMWF/ERA5_LAND/MONTHLY_AGGR', engine='ee', **grid)

7. Having trouble?

See the FAQ and open a discussion if needed.