Command-line interface¶
Leafmap installs command-line tools for viewing geospatial files in the browser without writing any code or starting Jupyter. They are handy for a quick look at a file on disk or at a URL.
| Command | Equivalent | Purpose | Requires |
|---|---|---|---|
view-raster |
leafmap view-raster |
View a raster (GeoTIFF, COG, ...) file | pip install "leafmap[raster]" |
view-vector |
leafmap view-vector |
View a vector (GeoJSON, Shapefile, ...) file | pip install "leafmap[maplibre]" |
Run any command with --help to see all of its options.
View a raster¶
view-raster starts a local tile server with localtileserver
and opens an interactive map in your default browser. The server keeps running
until you press Ctrl+C.
1 2 3 4 5 6 7 8 9 | |
Options:
| Option | Description |
|---|---|
--band, --indexes INDEXES |
Band index to display (1-based), or a comma-separated list for RGB |
--colormap COLORMAP |
Colormap name to apply to a single band (e.g., viridis, terrain) |
--vmin VMIN, --vmax VMAX |
Value range used for color mapping |
--nodata NODATA |
Nodata value to render as transparent |
--port PORT |
Port for the tile server (default: chosen automatically) |
--no-browser |
Do not open the browser; print the path of the generated HTML file instead |
View a vector¶
view-vector reads the file with geopandas, renders it with the MapLibre backend
and opens the resulting map in your browser.
1 2 | |
Options:
| Option | Description |
|---|---|
--style STYLE |
Basemap style, such as dark-matter (default), positron, voyager or liberty |
--no-browser |
Do not open the browser; print the path of the generated HTML file instead |
Python API¶
The same viewers are available from Python:
1 2 3 4 | |
leafmap.cli
¶
Command-line interface for leafmap.
main()
¶
Main CLI entry point.
view_raster(file_path, port=None, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, open_browser=True)
¶
View a raster file interactively in the browser using localtileserver.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str
|
Path or URL to the raster file to view. Supports both local paths and HTTP/HTTPS URLs. |
required |
port
|
int
|
Port to use for the tile server. Defaults to None. |
None
|
indexes
|
int | list[int]
|
Band index to display (1-based) or list of band indices for RGB visualization (e.g., [3, 2, 1]). Defaults to None. |
None
|
colormap
|
str
|
Colormap name to apply. Defaults to None. |
None
|
vmin
|
float
|
Minimum value for color mapping. Defaults to None. |
None
|
vmax
|
float
|
Maximum value for color mapping. Defaults to None. |
None
|
nodata
|
float
|
Nodata value to use. Defaults to None. |
None
|
open_browser
|
bool
|
Whether to open browser automatically. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the local raster file does not exist. |
ImportError
|
If localtileserver is not installed. |
view_raster_cli()
¶
Direct CLI entry point for view-raster command.
view_vector(file_path, style='dark-matter', open_browser=True)
¶
View a vector file interactively in the browser using maplibregl.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str
|
Path or URL to the vector file to view. Supports both local paths and HTTP/HTTPS URLs. |
required |
style
|
str
|
Map style. Defaults to "dark-matter". |
'dark-matter'
|
open_browser
|
bool
|
Whether to open browser automatically. Defaults to True. |
True
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the local vector file does not exist. |
ImportError
|
If required dependencies are not installed. |
view_vector_cli()
¶
Direct CLI entry point for view-vector command.