GDAL-VSI-LIST(1)

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>

COPYRIGHT
1998-2026