gdal-vsi-list - Man Page

Name

gdal-vsi-list — List files of one of the GDAL Virtual System Interface (VSI)

Added in version 3.11.

Synopsis

Usage: gdal vsi list [OPTIONS] <FILENAME>

List files of one of the GDAL Virtual System Interface (VSI).

Positional arguments:
  --filename <FILENAME>                                File or directory name [required]

Common Options:
  -h, --help                                           Display help message and exit
  --json-usage                                         Display usage as JSON document and exit
  --config <KEY>=<VALUE>                               Configuration option [may be repeated]

Options:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format. OUTPUT-FORMAT=json|text
  -l, --long, --long-listing                           Use a long listing format
  -R, --recursive                                      List subdirectories recursively
  --depth <DEPTH>                                      Maximum depth in recursive mode
  --abs, --absolute-path                               Display absolute path
  --tree                                               Use a hierarchical presentation for JSON output

Description

gdal vsi list list files of GDAL Virtual File Systems (compressed, network hosted, etc...): /vsimem, /vsizip, /vsitar, /vsicurl, ...​.

This is the equivalent of the UNIX ls command, and gdal vsi ls is an alias for gdal vsi list​.

By default, it outputs file names, at the immediate level, without details, and in JSON format.

Options

--filename <FILENAME>

Any file name or directory name, of one of the GDAL Virtual file systems. Required.

-f,  --of,  --format,  --output-format json|text

Which output format to use. Default is JSON, and starting with GDAL 3.12, text when invoked from command line.

-l,  --long,  --long-listing

Use a long listing format, adding permissions, file size and last modification date.

-R,  --recursive

List subdirectories recursively. By default the depth is unlimited, but it can be reduced with --depth​.

--depth <DEPTH>

Maximum depth in recursive mode. 1 corresponds to no recursion, 2 to the immediate subdirectories, etc.

--abs,  --absolute-path

Whether to report file names as absolute paths. By default, they are relative to the input file name.

--tree

Use a hierarchical presentation for JSON output, instead of a flat list. Only valid when --output-format is set to json (or let at its default value).

Return Status Code

The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution).

Examples

Example 1: Listing recursively files in /vsis3/bucket with details

$ gdal vsi list -lR /vsis3/bucket

Author

Even Rouault <even.rouault@spatialys.com>

Info

Aug 18, 2026 GDAL