Install & Compatibility
Where this runs
tested against v1.7.30 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.705s · 154.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.8s · import 1.660s · 155MB
155MB installed
● package 155MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ee
✓ import ee
✗ from earthengine_api import ee
The canonical import is 'import ee'. Direct import from the package structure is not typical for the main client library object.
This quickstart demonstrates how to authenticate, initialize the Earth Engine API, and perform a basic operation (loading an image collection and getting its size). Users must replace `your-earthengine-project-id` with their actual Google Cloud Project ID, which needs to have the Earth Engine API enabled and registered for use.
import ee
import os
# IMPORTANT: Replace 'your-earthengine-project-id' with your actual Google Cloud Project ID.
# This project must have the Earth Engine API enabled.
# If running in Colab or a local environment with gcloud SDK, ee.Authenticate() will open a browser for login.
# For service account authentication, set GOOGLE_APPLICATION_CREDENTIALS env var.
project_id = os.environ.get('EE_PROJECT', 'your-earthengine-project-id')
try:
ee.Authenticate()
ee.Initialize(project=project_id, opt_url='https://earthengine-api.googleapis.com')
print('Earth Engine initialized successfully.')
# Example: Load a Landsat 8 image collection and print its size.
collection = ee.ImageCollection('LANDSAT/LC08/C01/T1_SR')\
.filterDate('2020-01-01', '2020-01-31')
# All Earth Engine operations are server-side. To get a client-side value,
# use .getInfo(). Be mindful of data size when using getInfo().
print(f'Collection size: {collection.size().getInfo()}')
except ee.EEException as e:
print(f'Earth Engine initialization failed: {e}')
print('Please ensure you have registered for Earth Engine access, enabled the API for your Google Cloud Project, and authenticated.')
print('Refer to https://developers.google.com/earth-engine/guides/getstarted for setup instructions.')
except Exception as e:
print(f'An unexpected error occurred: {e}')
Debug
Known issues
breakingMajor changes to authentication mechanisms and the underlying API have occurred, particularly around November 2020 (v0.1.242) and subsequent updates up to March 2026. This includes removal of `use_cloud_api` and `data.startProcessing`, and shifts to the v1 API for asset property access.fixEnsure your `earthengine-api` library is updated (`pip install --upgrade earthengine-api`). Re-authenticate using `ee.Authenticate()` and update `ee.Initialize()` to explicitly pass a `project` ID. Adjust code accessing asset properties (e.g., `my_asset['properties']['title']`).
affects: <=0.1.242 and potentially later for auth updates
gotchaForgetting to call `ee.Authenticate()` and `ee.Initialize(project='your-project-id')` at the beginning of a script or session is a common error. This often results in 'Google Earth Engine API has not been used in project...' or 'Caller does not have required permission'.fixAlways include `ee.Authenticate()` (for interactive login) and `ee.Initialize(project='YOUR_CLOUD_PROJECT_ID')`. Ensure your Google Cloud Project has the Earth Engine API enabled and your account is registered for Earth Engine access.
affects: All versions
gotchaConfusing client-side (Python) operations with server-side (Earth Engine) operations. Earth Engine objects are computational graphs executed on Google's servers. Attempting to use Python functions directly on `ee.Object` instances without resolving them with `.getInfo()` will lead to errors (e.g., 'Cannot concatenate 'str' and 'ComputedObject' objects'). Using `.getInfo()` on large objects can also lead to browser locking or memory issues, especially within loops.fixUnderstand when an operation is client-side vs. server-side. Use `.getInfo()` only when you need to bring data to the client and be mindful of the data volume. Avoid calling `.getInfo()` inside `for` loops or mapped functions. Optimize server-side computations before fetching results.
affects: All versions
gotchaHitting server-side computation limits, such as 'User memory limit exceeded' or 'Too many concurrent aggregations'. This usually occurs with highly nested mapped functions or complex reductions over large datasets.fixOptimize your Earth Engine scripts. Filter data (spatial, temporal, spectral) early, combine reducers, and consider adjusting the `tileScale` parameter in computations. Review the debugging guide and optimization tips in the official documentation.
affects: All versions
Errors
Common errors & fixes
EEException: Earth Engine client library not initialized. Run ee.Initialize().
The Earth Engine Python client library requires explicit initialization with a Google Cloud Project ID before any Earth Engine operations can be performed, especially in environments like Google Colab or when using a recent version of the API.
fixAfter importing `ee`, call `ee.Authenticate()` and then `ee.Initialize(project='your-project-id')`. Replace 'your-project-id' with a valid Google Cloud Project ID where the Earth Engine API is enabled. If you encounter 'Earth Engine API has not been used in project XXX before or it is disabled', visit the provided Google Cloud Console link to enable the API for your project.
ModuleNotFoundError: No module named 'ee' OR AttributeError: module 'ee' has no attribute 'Initialize'
This typically occurs because the `earthengine-api` package is not installed, or a conflicting, unrelated Python package also named `ee` is installed and takes precedence in your Python environment. The `AttributeError` often means an older or incorrect `ee` module was imported.
fixFirst, ensure `earthengine-api` is correctly installed using `pip install earthengine-api` or `conda install -c conda-forge earthengine-api`. If the issue persists, check for other packages named `ee` in your environment (e.g., using `pip show ee`). Consider creating a new virtual environment to avoid package conflicts.
AttributeError: 'ComputedObject' object has no attribute 'get' OR AttributeError: 'Image' object has no attribute 'get'
You are attempting to directly access properties or call Python-style methods (like dictionary `get()`) on a server-side Earth Engine object (e.g., `ee.ComputedObject`, `ee.Image`, `ee.Feature`). Earth Engine objects are symbolic computations that reside on Google's servers, and their properties cannot be accessed directly in client-side Python without a server-side operation.
fixTo access properties of an Earth Engine object, you must use Earth Engine's server-side methods (e.g., `ee.Image.get('property_name')` for a property that is part of the EE object structure) or bring the object's information to the client-side by calling `.getInfo()` on the `ee.ComputedObject`. For example, `image.get('system:id').getInfo()` will retrieve the image ID as a Python string. HttpError 403: User does not have permission to access Google Earth Engine. OR DefaultCredentialsError: Could not automatically determine credentials.
These errors indicate a problem with authentication or permissions. Your Google account may not be registered for Earth Engine, the Earth Engine API might not be enabled for your selected Google Cloud Project, or the authentication tokens are expired, invalid, or missing.
fix1. Ensure your Google account is registered and approved for Earth Engine access at `code.earthengine.google.com/register`. 2. Run `earthengine authenticate` in your terminal or `ee.Authenticate()` in your Python script to re-authenticate and follow the browser prompts. 3. Ensure the Earth Engine API is enabled for your Google Cloud Project in the Google Cloud Console (APIs & Services > Library). 4. If using a service account, verify that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account key file with the necessary permissions.
Upgrade
Version history
1.7.30latest on PyPI · released Jun 8, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
google-cloud-sdkoptionalThe `gcloud` CLI is often used for initial authentication and project setup.