Install & Compatibility
Where this runs
tested against v0.21.0 · 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
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 14.0s · import 1.976s · 328MB
327MB installed
● package 327MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseProvider
✓ from pygeoapi.provider.base import BaseProvider
Used for developing custom data providers.
API
✓ from pygeoapi.api import API
Core API class, mainly used internally or for advanced customizations.
This quickstart generates a basic `pygeoapi-config.yml` file and provides instructions on how to set the necessary environment variables (`PYGEOAPI_CONFIG`, `PYGEOAPI_OPENAPI`), generate the OpenAPI document, and start the pygeoapi server. Users can then access the API through a web browser or programmatic clients.
import os
import yaml
# Define a minimal pygeoapi configuration
config_content = {
'server': {
'bind': {'host': '0.0.0.0', 'port': 5000},
'url': 'http://localhost:5000/',
'pretty_print': True
},
'logging': {
'level': 'DEBUG'
},
'metadata': {
'identification': {
'title': 'My pygeoapi instance',
'abstract': 'A minimal pygeoapi setup.',
'keywords': ['geospatial', 'API', 'OGC'],
'license': {'url': 'https://creativecommons.org/licenses/by/4.0/'}
},
'provider': {
'name': 'pygeoapi',
'url': 'https://pygeoapi.io/'
}
},
'resources': {
# Add sample data as needed. E.g., a GeoJSON file
# 'data': {
# 'type': 'collection',
# 'title': 'Sample GeoJSON Data',
# 'description': 'A sample collection from a GeoJSON file.',
# 'keywords': ['geojson', 'sample'],
# 'extents': {
# 'spatial': {'bbox': [-180, -90, 180, 90]},
# 'temporal': {'interval': ['1900-01-01T00:00:00Z', '2099-12-31T23:59:59Z']}
# },
# 'provider': {
# 'type': 'feature',
# 'name': 'GeoJSON',
# 'data': 'path/to/your/data.geojson'
# }
# }
}
}
config_file_path = 'pygeoapi-config.yml'
openapi_file_path = 'pygeoapi-openapi.yml'
with open(config_file_path, 'w') as f:
yaml.dump(config_content, f, sort_keys=False)
print(f"Generated minimal configuration file: {config_file_path}")
print(f"\nTo run pygeoapi:")
print(f"1. Set the configuration environment variable: ")
print(f" export PYGEOAPI_CONFIG={config_file_path}")
print(f"2. Generate the OpenAPI document (required for server startup):")
print(f" pygeoapi openapi generate $PYGEOAPI_CONFIG --output-file {openapi_file_path}")
print(f"3. Set the OpenAPI environment variable: ")
print(f" export PYGEOAPI_OPENAPI={openapi_file_path}")
print(f"4. Start the server:")
print(f" pygeoapi serve")
print(f"\nAccess your pygeoapi instance at http://localhost:5000 in your browser.")
pygeoapi --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'setuptools'
The `setuptools` package, while often pre-installed, is not part of the Python standard library and might be missing in minimal Python environments.
fixInstall `setuptools` explicitly: `pip install setuptools`.
pygeoapi server fails to start (e.g., 'Configuration file not found' or similar error messages related to config paths).
The `PYGEOAPI_CONFIG` environment variable is not set or points to a non-existent configuration file.
fixEnsure `PYGEOAPI_CONFIG` is set to the correct absolute path of your `pygeoapi-config.yml` file before running `pygeoapi serve`. Example: `export PYGEOAPI_CONFIG=$(pwd)/pygeoapi-config.yml`.
InvalidParameterValue: Invalid format
The client (e.g., web browser, curl) is making a request without specifying an acceptable format via the `f=` parameter or the `Accept` HTTP header, and pygeoapi cannot determine the preferred output.
fixAppend `?f=json` or `?f=html` to your API endpoint URL, or set the `Accept` HTTP header to `application/json` or `text/html`.
Errors related to SQLite extensions or `spatialite` on macOS, especially when using `pyenv`.
Incompatibilities or missing dependencies for SQLite spatial extensions when Python is managed by `pyenv` on macOS.
fixFollow the specific instructions in the pygeoapi documentation for 'Working with Spatialite on OSX' which often involves ensuring Homebrew and pyenv play nicely together and proper installation of `spatialite`.
Upgrade
Version history
0.23.4latest on PyPI · released Apr 27, 2026
Audit
Dependencies
No dependency data recorded yet.