Skip to content

Installation

Quick Install

CLI tool: 

pipx install geoparquet-io
# or: uv tool install geoparquet-io

Python library: 

pip install geoparquet-io
# or: uv add geoparquet-io

pipx and uv tool install the CLI in isolation while keeping it globally available. Use pip/uv add when you need the Python API in your project.

Installing Plugins

gpio supports plugins that add specialized format support. Install plugins alongside the main tool:

# Install with PMTiles support
uv tool install geoparquet-io --with gpio-pmtiles
pipx install geoparquet-io --preinstall gpio-pmtiles

# Add plugin to existing installation
uv tool install --with gpio-pmtiles geoparquet-io
pipx inject geoparquet-io gpio-pmtiles

Available plugins:

See the Plugins Guide for more information.

From Source

For the latest development version:

# Install from PyPI into current environment
uv pip install geoparquet-io

# Or install from source
git clone https://github.com/geoparquet/geoparquet-io.git
cd geoparquet-io
uv sync --all-extras

Requirements

  • Python: 3.10 or higher
  • PyArrow: 12.0.0+
  • DuckDB: 1.1.3+

All dependencies are automatically installed when you install geoparquet-io.

Optional Dependencies

Development Tools

For contributing to geoparquet-io:

uv sync --all-extras
# or
pip install geoparquet-io[dev]

This installs:

  • pytest for testing
  • ruff for linting
  • pre-commit for git hooks
  • mypy for type checking

Documentation

For building documentation:

uv pip install geoparquet-io[docs]
# or
pip install geoparquet-io[docs]

This installs:

  • mkdocs for documentation generation
  • mkdocs-material theme
  • mkdocstrings for API documentation

Verifying Installation

After installation, verify everything works:

# Check version
gpio --version

# Get help
gpio --help

# Run a simple command (requires a GeoParquet file)
gpio inspect your_file.parquet

Shell Completion

Enable tab completion for gpio commands in your shell:

Bash: 

# Add to ~/.bashrc
eval "$(_GPIO_COMPLETE=bash_source gpio)"

Zsh: 

# Add to ~/.zshrc
eval "$(_GPIO_COMPLETE=zsh_source gpio)"

Fish: 

# Add to ~/.config/fish/config.fish
eval (env _GPIO_COMPLETE=fish_source gpio)

After adding the appropriate line to your shell config, restart your shell or source the config file: 

source ~/.bashrc    # Bash
source ~/.zshrc     # Zsh
source ~/.config/fish/config.fish  # Fish

Once enabled, you can tab-complete commands, subcommands, and options: 

gpio <TAB>          # Shows: add, check, convert, extract, inspect, ...
gpio add <TAB>      # Shows: bbox, h3, kdtree, quadkey, ...
gpio add bbox --<TAB>  # Shows available options

Upgrading

To upgrade to the latest version:

# CLI tool
pipx upgrade geoparquet-io
# or: uv tool upgrade geoparquet-io

# Python library
pip install --upgrade geoparquet-io
# or: uv add geoparquet-io (automatically gets latest)

Uninstalling

To remove geoparquet-io:

# CLI tool
pipx uninstall geoparquet-io
# or: uv tool uninstall geoparquet-io

# Python library
pip uninstall geoparquet-io
# or: uv remove geoparquet-io

Platform Support

geoparquet-io is tested on:

  • Operating Systems: Linux, macOS, Windows
  • Python Versions: 3.10, 3.11, 3.12, 3.13
  • Architectures: x86_64, ARM64

Troubleshooting

DuckDB Installation Issues

If you encounter issues with DuckDB installation, try:

pip install --upgrade duckdb

PyArrow Compatibility

Ensure you have PyArrow 12.0.0 or higher:

pip install --upgrade pyarrow>=12.0.0

Using Virtual Environments with uv

uv automatically manages virtual environments, but if you need a fresh environment:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install geoparquet-io

Next Steps

Once installed, head to the Quick Start Guide to learn how to use geoparquet-io.