file upload

Upload single file to the given bucket.

Uploads the contents of the local file, and assigns the given name to the B2 file, possibly setting options like server-side encryption and retention.

A FIFO file (such as named pipe) can be given instead of regular file.

By default, file upload will compute the sha1 checksum of the file to be uploaded. But, if you already have it, you can provide it on the command line to save a little time.


Setting file retention mode to ‘compliance’ is irreversible - such files can only be ever deleted after their retention period passes, regardless of keys (master or not) used. This is especially dangerous when setting bucket default retention, as it may lead to high storage costs.

Content type is optional. If not set, it will be guessed.

The maximum number of upload threads to use to upload parts of a large file is specified by --threads. It has no effect on “small” files (under 200MB as of writing this).

Each fileInfo is of the form a=b.

By default, the file is broken into many parts to maximize upload parallelism and increase speed. Setting --min-part-size controls the minimal upload file part size. Part size must be in 5MB to 5GB range. Reference:

If the tqdm library is installed, progress bar is displayed on stderr. Without it, simple text progress is printed. Use --no-progress to disable progress reporting (marginally improves performance in some cases).

Use –threads to manually adjust the number of threads used in the operation. Otherwise, the number of threads will be automatically chosen.

To request SSE-B2 or SSE-C encryption for destination files, please set --destination-server-side-encryption=SSE-B2/SSE-C. The default algorithm is set to AES256 which can be changed with --destination-server-side-encryption-algorithm parameter. Using SSE-C requires providing B2_DESTINATION_SSE_C_KEY_B64 environment variable, containing the base64 encoded encryption key. If B2_DESTINATION_SSE_C_KEY_ID environment variable is provided, it’s value will be saved as sse_c_key_id in the uploaded file’s fileInfo.

Setting file retention settings requires the writeFileRetentions capability, and only works in bucket with fileLockEnabled=true. Providing --file-retention-mode requires providing --retain-until which has to be a future timestamp, in the form of an integer representing milliseconds since epoch. Leaving out these options results in a file retained according to bucket defaults.

Setting legal holds requires the writeFileLegalHolds capability, and only works in bucket with fileLockEnabled=true.

Use –incremental-mode to allow for incremental file uploads to safe bandwidth. This will only affect files, which have been appended to since last upload.

The --custom-upload-timestamp, in milliseconds-since-epoch, can be used to artificially change the upload timestamp of the file for the purpose of preserving retention policies after migration of data from other storage. The access to this feature is restricted - if you really need it, you’ll need to contact customer support to enable it temporarily for your account.

Requires capability:

  • writeFiles

b2 file upload [-h] [--content-type CONTENT_TYPE] [--sha1 SHA1] [--info INFO]
               [--custom-upload-timestamp CUSTOM_UPLOAD_TIMESTAMP]
               [--cache-control CACHE_CONTROL]
               [--content-disposition CONTENT_DISPOSITION]
               [--content-encoding CONTENT_ENCODING]
               [--content-language CONTENT_LANGUAGE] [--expires EXPIRES]
               [--min-part-size MIN_PART_SIZE] [--threads THREADS]
               [--destination-server-side-encryption {SSE-B2,SSE-C}]
               [--destination-server-side-encryption-algorithm {AES256}]
               [--legal-hold {on,off}]
               [--file-retention-mode {compliance,governance}]
               [--retain-until TIMESTAMP] [--incremental-mode]
               bucketName localFilePath b2FileName

Positional Arguments


name of the bucket where the file will be stored


path of the local file or stream to be uploaded


name file will be given when stored in B2

Named Arguments


MIME type of the file being uploaded. If not set it will be guessed.


SHA-1 of the data being uploaded for verifying file integrity


additional file info to be stored with the file. Can be used multiple times for different information.

Default: []


overrides object creation date. Expressed as a number of milliseconds since epoch.


optional Cache-Control header, value based on RFC 2616 section 14.9, example: ‘public, max-age=86400’)


optional Content-Disposition header, value based on RFC 2616 section 19.5.1, example: ‘attachment; filename=”fname.ext”’


optional Content-Encoding header, value based on RFC 2616 section 14.11, example: ‘gzip’


optional Content-Language header, value based on RFC 2616 section 14.12, example: ‘mi, en’


optional Expires header, value based on RFC 2616 section 14.21, example: ‘Thu, 01 Dec 2050 16:00:00 GMT’


minimum part size in bytes


progress will not be reported

Default: False


Possible choices: SSE-B2, SSE-C


Possible choices: AES256

Default: “AES256”


Possible choices: on, off


Possible choices: compliance, governance


Default: False