Installation

Prerequisites

Attention

geeViz uses Google Earth Engine (GEE) for much of its functionality. It requires an active Earth Engine account and associated Google Cloud Platform project ID.

If you have not signed up for GEE, please sign up at the Earth Engine registration page.

Installing Earth Engine API

geeViz will attempt to automatically install the earthengine-api package, but sometimes this fails for various reasons. If automatic installation fails, refer to the official Earth Engine Python installation guide for troubleshooting.

You can manually install the Earth Engine API package:

$ pip install earthengine-api

Installing geeViz

Once the Earth Engine API is installed, install geeViz using pip:

$ pip install geeViz

Authentication and Initialization

While geeViz will attempt to authenticate and initialize GEE automatically, it may not handle all authentication methods correctly. The authentication process changes frequently, so following the official Python installation directions is recommended.

Important

While many examples in geeViz do not explicitly initialize to a project in the example code, we strongly recommend following the best practice of initializing GEE to a project prior to importing any geeViz modules.

Recommended initialization pattern:

 1import ee
 2ee.Initialize(project='your-project-id')
 3import geeViz.geeView as gv
 4
 5# Create a map instance
 6Map = gv.Map
 7
 8# Add Earth Engine data to the map
 9Map.addLayer(someEEImage, {}, 'Some Image')
10
11# Display the map
12Map.view()

Replace 'your-project-id' with your actual Google Cloud Project ID.

Verification

To verify your installation, run the following in a Python shell:

import ee
import geeViz

# Initialize Earth Engine
ee.Initialize(project='your-project-id')

# Test basic functionality
print(f"geeViz version: {geeViz.__version__}")
print("Earth Engine initialized successfully!")

If no errors appear, your installation is complete.

AI-Assisted Development (Optional)

If you use an AI coding assistant — Cursor, VS Code with GitHub Copilot, Claude Code, Windsurf, or similar — geeViz ships with an MCP server that gives the AI live access to geeViz. Instead of generating code from memory (which is often wrong or outdated), the AI can look up real function signatures, read actual example scripts, execute and test code, and inspect your Earth Engine assets.

The mcp SDK is already included as a dependency of geeViz — no extra install needed. Just add a short config file for your editor.

Follow the editor-specific instructions in the MCP Server guide. The whole process takes about two minutes.

Note

The MCP server is entirely optional. geeViz works the same way it always has without it. MCP is for users who want their AI assistant to write better geeViz code.

Next Steps

  • Check out the Examples section for use case example scripts and notebooks

  • Review the API Reference section for detailed code documentation

  • Visit the Module Overview to understand the available modules and their purposes

  • Set up the MCP Server if you use an AI coding assistant