GDAL-VSI-SYNC(1)

💖 GDAL-VSI-SYNC 💖

okay bestie, this is the gdal-vsi-sync page from the GDAL manual and it is lowkey iconic — it's all about syncing files across the GDAL Virtual System Interface (VSI). it landed in version 3.11, so it's a fresh queen. let's get into it 🫶

---

✨ NAME ✨

gdal-vsi-sync — synchronize source and target file/directory located on GDAL Virtual System Interface (VSI)

and yes, Added in version 3.11. 💅

---

🎀 SYNOPSIS 🎀

Usage: gdal vsi sync [OPTIONS] <SOURCE> <DESTINATION>

Synchronize source and target file/directory located on GDAL Virtual System Interface (VSI).

Positional arguments:
  --source <SOURCE>                Source file or directory name [required]
  --destination <DESTINATION>      Destination 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]
  -q, --quiet                      Quiet mode (no progress bar or warning message) [not available in pipelines]

Options:
  -r, --recursive                  Synchronize recursively
  --strategy <STRATEGY>            Synchronization strategy. STRATEGY=timestamp|ETag|overwrite (default: timestamp)
  -j, --num-threads <NUM-THREADS>  Number of jobs (or ALL_CPUS)

like, look at that syntax. <SOURCE> and <DESTINATION>? both required, no cap. 🙈

---

🦋 DESCRIPTION 🦋

so gdal vsi sync synchronizes files and directories living on GDAL Virtual File Systems — think compressed, network hosted, etc... — like /vsimem, /vsizip, /vsitar, /vsicurl, .... 🌈

it's an analog to the UNIX rsync command, fr fr. but here's the tea: in the current implementation, rsync would actually be more efficient for local file copying. the real main character energy of gdal vsi sync shows up when the source or target is a remote file system like /vsis3/ or /vsigs/, because then it can take into account the timestamps of the files (or optionally the ETag/MD5Sum) to avoid unneeded copy operations. slay, no wasted work. ✨

this is implemented efficiently for:

• local filesystem <--> remote filesystem. 💖
• remote filesystem <--> remote filesystem, where the source and target remote filesystems are the same and one of /vsis3/, /vsigs/ or /vsiaz/. Or when the target is /vsiaz/ and the source is /vsis3/, /vsigs/, /vsiadls/ or /vsicurl/ 🔥

similarly to rsync behavior, if the source filename ends with a slash, it means that the content of the directory must be copied, but not the directory name. for example, assuming /home/even/foo contains a file bar, gdal vsi sync -r /home/even/foo/ /mnt/media will create a /mnt/media/bar file. whereas gdal vsi sync -r /home/even/foo /mnt/media will create a /mnt/media/foo directory which contains a bar file. that trailing slash is doing SO much work, iykyk. 🌸

and this is implemented by VSISync().

👑 Options 👑

• -r, --recursive — Synchronize recursively. go all the way down, bestie. 🕳️
• --strategy timestamp|ETag|overwrite — decides which criterion is used to determine if a target file must be replaced when it already exists and has the same file size as the source. Only applies for a source or target being a network filesystem. 🛰️

the default is timestamp (similarly to how aws s3 sync works). For an upload operation, a remote file is replaced if it has a different size or if it is older than the source. For a download operation, a local file is replaced if it has a different size or if it is newer than the remote file. 👀

the ETag strategy assumes that the ETag metadata of the remote file is the MD5Sum of the file content, which is only true in the case of /vsis3/ for files not using KMS server side encryption and uploaded in a single PUT operation (so smaller than 50 MB given the default used by GDAL). Only to be used for /vsis3/, /vsigs/ or other filesystems using a MD5Sum as ETAG. ⚠️ don't just spray this everywhere, it's a specific girlie.

the overwrite strategy will always overwrite the target file with the source one. no thoughts, head empty, just replace. 💀

• -j, --num-threads <value> — Number of jobs to run at once. multitasking queen 💅 (and the SYNTAX up top says it can be ALL_CPUS too, so go feral.)

---

🌟 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 like, a warning is NOT a fail, it's just a little warning ✨

---

💜 EXAMPLES 💜

⭐ Example 1: Synchronize a local directory onto a S3 bucket ⭐

$ gdal vsi sync -r my_directory/ /vsis3/bucket/my_directory

look at her go. 💖

---

🌈 AUTHOR 🌈

Even Rouault <even.rouault@spatialys.com>

---

🎀 COPYRIGHT 🎀

1998-2026

---

and that's the whole page, bestie 🫶 this was the GDAL-VSI-SYNC(1) manual — GDAL-flavored, dated Aug 18, 2026. go sync something and make it everybody's problem 💅✨🌸