zsync

Download a file using a .zsync control file

$ zsync [path/to/url.zsync]

$ zsync -i [path/to/existing_file] [path/to/url.zsync]

$ zsync -i [path/to/existing_file] -o [path/to/new_file] [path/to/url.zsync]

$ zsync -k [path/to/url.zsync]

$ zsync -q [path/to/url.zsync]

zsync [options] URL_OR_PATH_TO_ZSYNC_FILE [output_filename]

-o
    Specifies the local output filename. If not given, the filename is derived from the URL.

-u
    Provides a base URL to find the target file, especially if the .zsync file is local.

-i
    Instructs zsync to only check the existing file and generate a .zsync file for it, without downloading.

-s
    Similar to -i, used for scanning local files to generate .zsync data.

-q
    Runs in quiet mode, suppressing non-essential output.

-v
    Runs in verbose mode, providing more detailed output.

-k
    Keeps any partial files on error, allowing for manual inspection or later resumption.

-r
    Resumes an incomplete download, continuing from where it left off.

-f
    Forces download even if the local file appears to be identical to the remote.

-w
    Don't download; instead, output the URL of the .zsync file that would be used.

-H
    Adds a custom HTTP header to requests (e.g., User-Agent: myapp/1.0).

-A
    Sets the HTTP User-Agent string for requests.

-b
    Enables batch mode, suitable for scripting.

--help
    Displays help information and exits.

--version
    Displays version information and exits.

zsync is a file transfer program that allows for efficient downloading of files, especially when a previous version or part of the file already exists locally. It operates similarly to rsync by employing the same delta-transfer algorithm, which intelligently identifies and transfers only the changed blocks or differences between the local file and the remote target file. This significantly reduces the amount of data transferred, making it highly bandwidth-efficient and faster for updates to large files.

Unlike rsync, which is a general-purpose synchronization tool often used for server-to-server transfers, zsync is specifically designed for one-way downloads from HTTP/HTTPS web servers or local file paths. It requires a small .zsync control file, which contains checksums and block information about the target file, to be available alongside the file on the server. zsync uses this control file to determine which blocks of the local file need updating, then requests only those specific ranges from the web server using HTTP range requests. This makes zsync ideal for distributing software updates, large datasets, or any files where minor changes are frequent and users might have an older version.

• Requires a pre-generated .zsync control file (e.g., filename.zsync) to be present and accessible alongside the target file on the server.
• The web server serving the target file must support HTTP Range Requests, which allows zsync to download only specific parts of the file.
• zsync is a one-way download utility, not a bidirectional synchronization tool like rsync.
• For very small files or entirely new files, the overhead of checking checksums might make zsync slightly slower than a direct full download with tools like wget or curl.

To use zsync, a .zsync control file must first be created from the target file. This is typically done using the zsyncmake utility (often packaged with zsync). For example, zsyncmake largefile.iso would create largefile.iso.zsync. This .zsync file then needs to be made available on the web server alongside largefile.iso.

For zsync to function correctly, the web server hosting the target file must support HTTP Range Requests (RFC 7233). This feature allows zsync to request only specific byte ranges of the file, which is crucial for its delta-transfer mechanism. Most modern web servers (e.g., Apache, Nginx) support this by default.

zsync was developed by Colin Phipps, inspired by the efficiency of the rsync algorithm. Its primary goal was to adapt this powerful delta-transfer mechanism for use over HTTP, enabling bandwidth-efficient file updates from standard web servers. It gained some traction in projects requiring efficient distribution of large files, such as Linux distribution ISO updates or game patches, where users often have an older version of the file locally. While not as widely known as rsync, it fills a specific niche for efficient web-based downloads requiring partial file updates.

rsync(1), wget(1), curl(1)