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