download

Available in Classic and VPC

Download objects in a container (bucket).

Syntax

The download syntax is as follows:

Account (downloads all containers and objects)

swift download \
    --all \
    [--marker <marker>] \
    [--prefix <prefix>] \
    [--remove-prefix] \
    [--output-dir <out-directory>] \
    [--object-threads <threads>] \
    [--container-threads <threads>] \
    [--no-download] \
    [--skip-identical] \
    [--ignore-checksum] \
    [--ignore-mtime] \
    [--no-shuffle] \
    [--header <header:value>]

Container (downloads all objects within the container)

swift download \
    <container> \
    [--marker <marker>] \
    [--prefix <prefix>] \
    [--remove-prefix] \
    [--output-dir <out-directory>] \
    [--object-threads <threads>] \
    [--container-threads <threads>] \
    [--no-download] \
    [--skip-identical] \
    [--ignore-checksum] \
    [--ignore-mtime] \
    [--no-shuffle] \
    [--header <header:value>]

Object (downloads a single or multiple objects)

swift download \
    <container> <object> [<object> ...] \
    [--output <out-file>] \
    [--output-dir <out-directory>] \
    [--object-threads <threads>] \
    [--no-download] \
    [--skip-identical] \
    [--ignore-checksum] \
    [--ignore-mtime] \
    [--header <header:value>]

Options

This section describes the options available when running download.

Required options

The following options are required for download.

Options	Type	Required	Description
`<container>`	String	Conditional	Container name Required when `--all` is not entered
`--all`	Boolean	Conditional	Downloads all objects in an account. Required when not entering `<container>`.

Optional options

These are the optional options for download. Options that are not specified will use their default values.

Options	Type	Required	Description
`<object>`	List	Optional	Object name Multiple entries are allowed, separated by spaces. If left blank, downloads all objects in the container.
`--prefix`	String	Optional	Downloads only items that begin with the specified prefix.
`--remove-prefix`	Boolean	Optional	Saves as the name excluding the prefix. Use along with `--prefix`.
`--marker`	String	Optional	Base location from which to start downloading containers or accounts
`--output`	String	Optional	File path to save to when downloading a single file Passes standard output if `-` is entered.
`--output-dir`	String	Optional	Directory to save objects in If left blank, saves to the current directory. Can't be used if only one object is specified (use `--output` instead).
`--no-download`	Boolean	Optional	Performs the download but does not save it to disk.
`--skip-identical`	Boolean	Optional	Does not download objects if they match local files.
`--ignore-checksum`	Boolean	Optional	Disables checksum validation during download.
`--ignore-mtime`	Boolean	Optional	Ignores the `X-Object-Meta-Mtime` header and saves with the new timestamp.
`--no-shuffle`	Boolean	Optional	Downloads objects in the order they appear in the object store If left blank, downloads in random order.
`--object-threads`	Integer	Optional	Number of threads to use for downloading objects Default: `10`
`--container-threads`	Integer	Optional	Number of threads to use for container downloads Default: `10`
`--header`	String	Optional	Custom header to use in download requests Enter in `header:value` format. Can be entered multiple times.

Common options

For information about the options common to all swift subcommands, see Archive Storage options.

Examples

When you run the command, the names of the downloaded objects and the time taken will be displayed.

Command

The following is an example command for downloading a single object.

swift download test-container-01 sample.txt

The following is an example command that uses a prefix to filter files, specifies a save directory, and skips duplicate files.

swift download test-container-01 \
    --prefix docs/ \
    --output-dir ./download \
    --skip-identical

The following is an example command for downloading all objects in an account in order.

swift download \
    --all \
    --no-shuffle

Output

The following is an example output for downloading a single object.

sample.txt [auth 0.000s, headers 0.109s, total 0.109s, 0.000 MB/s]

The following is an example output for downloading files filtered by prefix.

./download/docs/report.txt [auth 0.000s, headers 0.071s, total 0.071s, 0.000 MB/s]

The following is an example output for downloading all objects in an account.

test-container-01/renamed.txt [auth 0.000s, headers 0.129s, total 0.129s, 0.000 MB/s]
test-container-01/sample.txt [auth 0.000s, headers 0.132s, total 0.132s, 0.000 MB/s]
test-container-01/large.bin [auth 0.000s, headers 0.236s, total 0.372s, 14.090 MB/s]