GDAL-VSI-LIST(1)

📦
version 3.13.3 · 7 versions
, in alpine 3.24, arch rolling, ubuntu stonking

🌸 NAME 🌸

gdal-vsi-list — the lil' bestie that lists the files of one of the GDAL Virtual System Interface (VSI) 💖

No cap, this was 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 🦋

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

It's literally the equivalent of the UNIX ls command, and plot twist — gdal vsi ls is an alias for gdal vsi list. Same energy, shorter name. 💅

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

💜 Options 💜

  • --filename <FILENAME> — Any file name or directory name, of one of the GDAL Virtual file systems. This one is Required, so like… you literally cannot skip it bestie. 🙈
  • -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. The glow-up is real. 🔥
  • -l, --long, --long-listing — Use a long listing format, adding permissions, file size and last modification date. The full tea ☕ — you get the receipts.
  • -R, --recursive — List subdirectories recursively. By default the depth is unlimited, but it can be reduced with --depth. She goes deep. 💀
  • --depth <DEPTH> — Maximum depth in recursive mode. 1 corresponds to no recursion, 2 to the immediate subdirectories, etc. So 1 is giving "I'm staying home" and bigger numbers are giving "let me snoop". 🧚
  • --abs, --absolute-path — Whether to report file names as absolute paths. By default, they are relative to the input file name. Both are valid, pick your main character energy. 👑
  • --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). So don't be trying this with text, she will not tolerate it. 🎀

⭐ 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). So if it's just out here losing the plot quietly with warnings, that's still a slay by the exit code's standards. 💖

🌈 EXAMPLES 🌈

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

$ gdal vsi list -lR /vsis3/bucket

Look at her go. Recursive and long-listing in one tiny little command. Ate. 🔥

🌸 AUTHOR 🌸

Even Rouault <even.rouault@spatialys.com> — the legend herself, we stan. 👑

1998-2026

and that's the whole vibe check, bestie 🎀 this page came to you from the GDAL manual, dated Aug 18, 2026, under the name GDAL-VSI-LIST(1). now go list some files, fr fr 💅✨

📦 where this page comes from