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 from pip:
pip install --upgrade xeeInstall from conda-forge:
conda install -c conda-forge xee:class: note
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:
```shell
pip install --upgrade --pre xee
Or pin a specific release candidate:
pip install xee==0.1.1rc1Prerelease builds are not published to Conda-Forge.
## Earth Engine setup
Xee makes requests to [Google Earth
Engine](https://developers.google.com/earth-engine/guides) 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](quickstart.md).
**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](https://developers.google.com/earth-engine/guides/auth).
### 1. Create and register a Cloud project
Follow instructions in the [Earth Engine Access
guide](https://developers.google.com/earth-engine/guides/access#get_access_to_earth_engine
) 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](https://developers.google.com/earth-engine/guides/command_line#authenticate):
```shell
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.
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.
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.
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'
)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.