Google Earth Engine
Batch
Uploader
geeup is a comprehensive command-line tool designed to simplify data preparation and batch uploading to Google Earth Engine. Handle images, shapefiles, and metadata with retry logic and parallel processing.
Main Interface
The geeup tool uses a subcommand structure. Run geeup -h to see
all available commands and arguments.
usage: geeup [-h] {readme,quota,auth,rename,zipshape,getmeta,cookie_setup,upload,tabup,tasks,cancel,delete} ...
Simple Client for Earth Engine Uploads with Enhanced UI and Service Account Support
positional arguments:
{readme,quota,auth,rename,zipshape,getmeta,cookie_setup,upload,tabup,tasks,cancel,delete}
readme Open the geeup documentation page
quota Print Earth Engine storage and asset count quota with visual progress bars
auth Configure service account authentication
rename Rename files to adhere to EE naming rules with interactive preview
zipshape Zip all shapefiles and subsidiary files in folder with progress tracking
getmeta Create generalized metadata for rasters in folder with progress tracking
cookie_setup Setup cookies to be used for upload
upload Batch Image Uploader for uploading TIF files to a GEE collection
tabup Batch Table Uploader for uploading shapefiles/CSVs to a GEE folder
tasks Query current task status with rich formatting [completed, running, ready, failed, cancelled]
cancel Cancel all, running, pending tasks or specific task ID with progress tracking
delete Delete collection and all items inside recursively
options:
-h, --help show this help message and exit
Installation
Method 1: PyPI (Recommended)
pip install geeup
Requirement: Ensure you have the Earth Engine Python API installed and
authenticated via earthengine authenticate.
Cookie Setup
The cookie_setup tool is an essential step for configuring uploads. It utilizes a
third-party Chrome extension called
Copy
Cookies.
This extension simplifies the process of copying the necessary authentication cookies from your
browser to the geeup tool. Please note that geeup does not provide support or warranty for the
extension.
How to set up your cookies:
- Install the Chrome Extension: Install the Copy Cookies extension in your Chrome browser.
- Copy Cookies: Log into code.earthengine.google.com. Once logged in, click the extension icon to copy the required cookies to your clipboard.
Running the Setup
To run the setup method, parse the copied cookies, and save them for use, run the following command and paste your clipboard content when prompted:
geeup cookie_setupImportant Notes
- Use a Fresh Browser Window: Open a new browser window (not incognito) to ensure all necessary cookies are loaded correctly.
- Clear Cookies on Error: If your upload fails with an "Unable to read" error, clear your browser cookies and try copying them again from a fresh instance.
- Matching Accounts: Ensure you save cookies for the same Earth
Engine account you initialized using
earthengine authenticate.
Bash Users
Canonical mode limits pasting to 4095 characters. If geeup cookie_setup fails,
try this:
- stty -icanon
- geeup cookie_setup
- stty icanon
Mac Users
You may need to change your default login shell from /bin/zsh to
/bin/sh to ensure the stty -icanon command works as expected.
Reference Issue #41.
Service Account Configuration
The geeup auth command handles service account configuration. This allows for automated
workflows without manual authentication prompts and enables switching between different GEE accounts
easily. You can authenticate using a JSON key file, check your current status, or remove
credentials.
# Initialize with a service account key
geeup auth --cred "/path/to/service-account.json"
# Check which account is currently configured
geeup auth --status
# Remove the current credentials
geeup auth --remove| Argument | Description |
|---|---|
| --credOptional | Path to service account JSON credentials file. Used to authenticate. |
| --statusOptional | Show current authentication status and the active service account email. |
| --removeOptional | Remove stored service account credentials and revert to default authentication. |
Rename Files
The rename command sanitizes filenames in a directory to ensure they strictly adhere to
Earth Engine naming conventions. It removes spaces and special characters that cause upload
failures. By default, it runs interactively, showing a preview of changes.
geeup rename --input "./raw_data" --batch| Argument | Description |
|---|---|
| --inputRequired | Path to the input directory containing files to be renamed. |
| --batchOptional | Skip confirmation prompt and automatically rename all files found. |
Zip Shapefiles
The zipshape tool scans a directory for shapefile components (e.g., .shp, .shx, .dbf,
.prj) and intelligently packages them into individual ZIP archives. This is a required step before
uploading vectors (Table Upload).
geeup zipshape --input "./vectors" --output "./zipped_vectors"| Argument | Description |
|---|---|
| --inputRequired | Path to the input directory containing raw shapefiles. |
| --outputRequired | Destination folder where the created ZIP archives will be stored. |
Generate Metadata
The getmeta command generates a metadata CSV file for a folder of rasters. This CSV is
essential for the batch uploader, as it defines properties like image IDs, dimensions, and data
types.
geeup getmeta --input "./rasters" --metadata "./metadata.csv"| Argument | Description |
|---|---|
| --inputRequired | Path to the input directory containing raster (TIF) files. |
| --metadataRequired | Full path (including filename) to export the generated metadata CSV file. |
Upload Images
The upload command is the core feature of geeup. It batch uploads GeoTIFF files to an
Earth Engine Image Collection. It supports advanced features like automatic retries for failed
tasks, parallel worker threads, resumption of interrupted jobs, and dry runs for validation.
# Comprehensive Upload Example
geeup upload --source "./rasters" \
--dest "users/username/collection" \
--metadata "./metadata.csv" \
--user "[email protected]" \
--workers 4 \
--resume| Argument | Description |
|---|---|
| --sourceRequired | Path to the directory with images for upload. |
| --destRequired | Destination path for GEE Image Collection
(e.g., users/you/collection). |
| --metadata, -mRequired | Path to the metadata CSV file. |
| --user, -uRequired | Google account email address used for authentication. |
| --nodataOptional | Integer value to burn into the raster as NoData (missing data). |
| --maskOptional | Boolean (True/False). Use the last band as a validity mask. |
| --pyramidsOptional | Pyramiding Policy: MEAN, MODE, MIN, MAX, SAMPLE. Default: MEAN. |
| --overwriteOptional | Overwrite existing assets? Pass 'yes' or 'y'. Default: No. |
| --dry-runOptional | Run validation logic without actually uploading files. |
| --workersOptional | Number of parallel upload workers (threads). Default: 1. |
| --max-inflight-tasksOptional | Maximum concurrent EE tasks allowed. Default: 2800. |
| --resumeOptional | Resume from previous state, skipping already uploaded files. |
| --retry-failedOptional | Retry only the uploads that previously failed. |
Tabup (Table Upload)
The tabup command is designed for batch uploading table data (vectors). It accepts
folders containing zipped shapefiles or CSVs and uploads them to a specified GEE folder.
geeup tabup --source "./zipped_vectors" \
--dest "users/username/folder" \
--user "[email protected]" \
--max-error-meters 1.0| Argument | Description |
|---|---|
| --sourceRequired | Path to the directory with zipped files or CSV files. |
| --destRequired | Destination path for GEE Folder (e.g.,
users/you/folder).
|
| --user, -uRequired | Google account email address used for authentication. |
| --xOptional | Column name containing longitude values (for CSVs). |
| --yOptional | Column name containing latitude values (for CSVs). |
| --metadataOptional | Path to CSV with metadata. |
| --overwriteOptional | Overwrite existing assets? Pass 'yes' or 'y'. |
| --max-error-metersOptional | Maximum allowed error in meters for geometry. Default: 1.0. |
| --max-verticesOptional | Maximum vertices per geometry feature. Default: 1000000. |
| --workersOptional | Number of parallel upload workers. Default: 1. |
Check Quota
The quota command prints your Earth Engine storage usage and asset counts with visual
progress bars. It supports checking specific cloud projects.
geeup quota --project "projects/my-project"| Argument | Description |
|---|---|
| --projectOptional | Project Name, usually in the format
projects/project-name/assets/.
|
Task Status
The tasks command allows you to query the status of your Earth Engine tasks. You can
view a summary of all tasks or filter by state and ID.
geeup tasks --state RUNNING| Argument | Description |
|---|---|
| --stateOptional | Query by state type:
COMPLETED, READY, RUNNING,
FAILED, or CANCELLED.
|
| --idOptional | Query for a specific task ID. |
Cancel Tasks
The cancel command provides a quick way to stop tasks. You can cancel specific task IDs
or bulk cancel all tasks in a 'running' or 'pending' state.
geeup cancel --tasks running| Argument | Description |
|---|---|
| --tasksRequired | Provide all,
running, pending, or a specific task ID string.
|
Recursively Delete
The delete command recursively removes a collection and all assets inside it. Use with caution as this action cannot be undone.
geeup delete --id "users/username/test_collection"| Argument | Description |
|---|---|
| --idRequired | Full path to the asset (collection or image) for deletion. |
Readme
The readme command simply opens the official documentation in your default web browser.
geeup readme
Usage Analytics
Live view of tool usage statistics and metrics.