---
name: "gdal-vsi-list"
section: "1"
platform: "linux"
package: "gdal"
version: "3.13.3-6"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gdal-vsi-list"
---

# gdal-vsi-list(1)

List files of one of the GDAL Virtual System Interface (VSI) Added in version 3.11.

## 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