Skip to content

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
# Single-band raster with a colormap
view-raster dem.tif --colormap terrain

# False-color composite from bands 4, 3 and 2
view-raster landsat.tif --indexes 4,3,2

# Cloud Optimized GeoTIFF from a URL with a fixed value range
view-raster https://github.com/opengeos/datasets/releases/download/raster/srtm90.tif \
    --colormap terrain --vmin 0 --vmax 4000

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
view-vector countries.geojson
view-vector https://github.com/opengeos/datasets/releases/download/vector/countries.geojson --style positron

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
from leafmap.cli import view_raster, view_vector

view_raster("dem.tif", colormap="terrain")
view_vector("countries.geojson", style="positron")

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.