`mc cp`

Syntax

The mc cp command copies objects to or from a MinIO deployment, where the source can MinIO or a local filesystem.

You can also use mc cp against the local filesystem to produce similar results to the cp commandline tool.

Note

mc cp only copies the latest version or the specified version of an object without any version information or modification date. To copy all versions, version information, and related metadata, use mc replicate add or mc admin replicate.

EXAMPLE

The following command copies files from a local filesystem directory to the mydata bucket on the myminio MinIO deployment:

mc cp --recursive ~/mydata/ myminio/mydata/

SYNTAX

The mc cp command has the following syntax:

mc [GLOBALFLAGS] cp                                                        \
                 [--attr "string"]                                         \
                 [--disable-multipart]                                     \
                 [--enc-kms "string"]                                      \
                 [--enc-s3 "string"]                                       \
                 [--enc-c "string"]                                        \
                 [--legal-hold "on"]                                       \
                 [--limit-download string]                                 \
                 [--limit-upload string]                                   \
                 [--md5]                                                   \
                 [--newer-than "string"]                                   \
                 [--older-than "string"]                                   \
                 [--preserve]                                              \
                 [--recursive]                                             \
                 [--retention-mode "string" --retention-duration "string"] \
                 [--rewind "string"]                                       \
                 [--storage-class "string"]                                \
                 [--tags "string"]                                         \
                 [--version-id "string"]                                   \
                 [--zip]                                                   \
                 SOURCE [SOURCE ...]                                       \
                 TARGET

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

SOURCE

Required

The object or objects to copy.

For copying an object from MinIO, specify the alias and the full path to that object (e.g. bucket and path to object). For example:

mc cp play/mybucket/object.txt ~/mydata/object.txt

Specify multiple SOURCE paths to copy multiple objects to the specified TARGET. mc cp treats the last specified alias or filesystem path as the TARGET. For example:

mc cp ~/data/object.txt myminio/mydata/object.txt play/mydata/

For copying an object from a local filesystem, specify the full path to that object. For example:

mc cp ~/mydata/object.txt play/mybucket/object.txt

If you specify a directory or bucket to SOURCE, you must also specify --recursive to recursively copy the contents of that directory or bucket. If you omit the --recursive argument, cp only copies objects in the top level of the specified directory or bucket.

TARGET

Required

The full path to which mc cp copies the object.

For copying an object to MinIO, specify the alias and the full path to that object (e.g. bucket and path to object). For example:

mc cp ~/mydata/object.txt play/mybucket/object.txt

For copying an object from a local filesystem, specify the full path to that object. For example:

mc cp play/mybucket/object.txt ~/mydata/object.txt

--attr: Optional
Add custom metadata for the object. Specify key-value pairs as KEY=VALUE\;. For example, --attr key1=value1\;key2=value2\;key3=value3.

--checksum

Optional

New in version RELEASE.2024-10-02T08-27-28Z.

Add a checksum to an uploaded object.

Valid values are: - MD5 - CRC32 - CRC32C - SHA1 - SHA256

The flag requires server trailing headers and works with AWS or MinIO targets.

--disable-multipart: Optional
Disables multipart upload for the copy session.

--enc-kms

Encrypt or decrypt objects using server-side SSE-KMS encryption with client-managed keys.

The parameter accepts a key-value pair formatted as KEY=VALUE

`KEY`	The full path to the object as `alias/bucket/path/object.ext`. You can specify only the top-level path to use a single encryption key for all operations in that path.
`VALUE`	Specify an existing data key on the external KMS. See the `mc admin kms key create` reference for creating data keys.

KEY

The full path to the object as alias/bucket/path/object.ext.

You can specify only the top-level path to use a single encryption key for all operations in that path.

VALUE

Specify an existing data key on the external KMS.

See the mc admin kms key create reference for creating data keys.

For example:

--enc-kms "myminio/mybucket/prefix/object.obj=mybucketencryptionkey"

You can specify multiple encryption keys by repeating the parameter.

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-kms "myminio/mybucket/prefix/=mybucketencryptionkey"

--enc-s3

Optional

Encrypt or decrypt objects using server-side SSE-S3 encryption with KMS-managed keys. Specify the full path to the object as alias/bucket/prefix/object.

For example:

--enc-s3 "myminio/mybucket/prefix/object.obj"

You can specify the parameter multiple times to denote different object(s) to encrypt:

--enc-s3 "myminio/mybucket/foo/fooobject.obj" --enc-s3 "myminio/mybucket/bar/barobject.obj"

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-s3 "myminio/mybucket/foo"

--enc-c

Optional

Encrypt or decrypt objects using server-side SSE-C encryption with client-managed keys.

The parameter accepts a key-value pair formatted as KEY=VALUE

`KEY`	The full path to the object as `alias/bucket/path/object.ext`. You can specify only the top-level path to use a single encryption key for all operations in that path.
`VALUE`	Specify either a 32-byte RawBase64-encoded key or a 64-byte hex-encoded key for use with SSE-C encryption. Raw Base64 encoding rejects `=`-padded keys. Omit the padding or use a Base64 encoder that supports RAW formatting.

KEY

The full path to the object as alias/bucket/path/object.ext.

You can specify only the top-level path to use a single encryption key for all operations in that path.

VALUE

Specify either a 32-byte RawBase64-encoded key or a 64-byte hex-encoded key for use with SSE-C encryption.

Raw Base64 encoding rejects =-padded keys. Omit the padding or use a Base64 encoder that supports RAW formatting.

KEY - the full path to the object as alias/bucket/path/object.
VALUE - the 32-byte RAW Base64-encoded data key to use for encrypting object(s).

For example:

# RawBase64-Encoded string "mybucket32byteencryptionkeyssec"
--enc-c "myminio/mybucket/prefix/object.obj=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo"

You can specify multiple encryption keys by repeating the parameter.

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-c "myminio/mybucket/prefix/=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo"

Note

MinIO strongly recommends against using SSE-C encryption in production workloads. Use SSE-KMS via the --enc-kms or SSE-S3 via --enc-s3 parameters instead.

--legal-hold

Optional

Enables indefinite legal hold object locking on the copied objects.

Specify on.

--limit-download

Optional

Limit client-side download rates to no more than a specified rate in KiB/s, MiB/s, or GiB/s. This affects only the download to the local device running the MinIO Client. Valid units include:

B for bytes
K for kilobytes
M for megabytes
G for gigabytes
T for terabytes
Ki for kibibytes
Mi for mibibytes
Gi for gibibytes
Ti for tebibytes

For example, to limit download rates to no more than 1 GiB/s, use the following:

--limit-download 1G

If not specified, MinIO uses an unlimited download rate.

--limit-upload

Optional

Limit client-side upload rates to no more than the specified rate in KiB/s, MiB/s, or GiB/s. This affects only the upload from the local device running the MinIO Client. Valid units include:

B for bytes
K for kilobytes
M for megabytes
G for gigabytes
T for terabytes
Ki for kibibytes
Mi for mibibytes
Gi for gibibytes
Ti for tebibytes

For example, to limit upload rates to no more than 1 GiB/s, use the following:

--limit-upload 1G

If not specified, MinIO uses an unlimited upload rate.

--md5: Optional

Changed in version RELEASE.2024-10-02T08-27-28Z: Replaced by the --checksum flag.

Forces all uploads to calculate MD5 checksums.

--newer-than

Optional

Copy object(s) newer than the specified number of days. Specify a string in #d#hh#mm#ss format. For example: --older-than 1d2hh3mm4ss

Defaults to 0 (all objects).

--older-than

Optional

Copy object(s) older than the specified time limit. Specify a string in #d#hh#mm#ss format. For example: --older-than 1d2hh3mm4ss

Defaults to 0 (all objects).

--preserve, a: Optional
Preserve file system attributes and bucket policy rules of the SOURCE directories, buckets, and objects on the TARGET bucket(s).

--recursive, r: Optional
Recursively copy the contents of each bucket or directory SOURCE to the TARGET bucket.

--retention-duration

Optional

The duration of the WORM retention mode to apply to the copied object(s).

Specify the duration as a string in #d#hh#mm#ss format. For example: --retention-duration "1d2hh3mm4ss".

Requires specifying --retention-mode.

--retention-mode

Optional

Enables object locking mode on the copied object(s). Supports the following values:

GOVERNANCE
COMPLIANCE

Requires specifying --retention-duration.

--rewind

Optional

Directs mc cp to operate only on the object version(s) that existed at specified point-in-time.

To rewind to a specific date in the past, specify the date as an ISO8601-formatted timestamp. For example: --rewind "2020.03.24T10:00".
To rewind a duration in time, specify the duration as a string in #d#hh#mm#ss format. For example: --rewind "1d2hh3mm4ss".

--rewind requires that the specified SOURCE be an S3-compatible service that supports Bucket Versioning. For MinIO deployments, use mc version to enable or disable bucket versioning.

--storage-class, sc

Optional

Set the storage class for the new object(s) on the TARGET.

See https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html for more information on S3 storage classes.

--tags

Optional

Applies one or more tags to the copied objects.

Specify an ampersand-separated list of key-value pairs as KEY1=VALUE1&KEY2=VALUE2, where each pair represents one tag to assign to the objects.

--version-id, vid

Optional

Directs mc cp to operate only on the specified object version.

--version-id requires that the specified SOURCE be an S3-compatible service that supports Bucket Versioning. For MinIO deployments, use mc version to enable or disable bucket versioning.

--zip: Optional
During copy, extract files from a .zip archive. Only functional when the source archive file exists on a MinIO deployment.

Global Flags

This command supports any of the global flags.

Examples

Copy Object to S3

Use mc cp to copy an object to an S3-compatible host:

Filesystem to S3

mc cp SOURCE ALIAS/PATH

Replace SOURCE with the filesystem path to the object.
Replace ALIAS with the alias of a configured S3-compatible host.
Replace PATH with the path to the object on the S3-compatible host. You can specify a different object name to “rename” the object on copy.

S3 to S3

mc cp SRCALIAS/SRCPATH TGTALIAS/TGTPATH

Replace SRCALIAS with the alias of a source S3-compatible host.
Replace SRCPATH with the path to the object on the S3-compatible host.
Replace TGTALIAS with the alias of a target S3-compatible host.
Replace TGTPATH with the path to the object on a target S3-compatible host. Omit the object name to use the SRCPATH object name.

Recursively Copy Objects to S3

Use mc cp --recursive to recursively copy objects to an S3-compatible host:

Filesystem to S3

mc cp --recursive SOURCE ALIAS/PATH

Replace SOURCE with the filesystem path to the directory containing the file(s).
Replace ALIAS with the alias of a configured S3-compatible host.
Replace PATH with the path to the object on the S3-compatible host. mc cp uses the SOURCE filenames when creating the objects on the target host.

S3 to S3

mc cp --recursive SRCALIAS/SRCPATH TGTALIAS/TGTPATH

Replace SRCALIAS with the alias of a source S3-compatible host.
Replace SRCPATH with the path to the bucket or bucket prefix on the source S3-compatible host.
Replace TGTALIAS with the alias of a target S3-compatible host.
Replace TGTPATH with the path to the object on the target S3-compatible host. mc cp uses the SRCPATH object names when creating objects on the target host.

Copy Point-In-Time Version of Object

Use mc cp --rewind to copy an object as it existed at a specific point in time. This command only applies to S3-to-S3 copy.

mc cp --rewind DURATION SRCALIAS/SRCPATH TGTALIAS/TGTPATH

Replace DURATION with the point-in-time in the past at which the command copies the object. For example, specify 30d to copy the version of the object 30 days prior to the current date.
Replace SRCALIAS with the alias of a source S3-compatible host.
Replace SRCPATH with the path to the object on the source S3-compatible host.
Replace TGTALIAS with the alias of a target S3-compatible host.
Replace TGTPATH with the path to the object on the target S3-compatible host. Omit the object name to use the SRCPATH object name.

Requires Versioning

mc cp requires bucket versioning to use this feature. Use mc version to enable versioning on a bucket.

Copy Specific Version of Object

Use mc cp --version-id to copy a specific version of an object. This command only applies to S3-to-S3 copy.

mc cp --version-id VERSION SRCALIAS/SRCPATH TGTALIAS/TGTPATH

Replace VERSION with the version of the object to copy.
Replace SRCALIAS with the alias of a source S3-compatible host.
Replace SRCPATH with the path to the object on the source S3-compatible host.
Replace TGTALIAS with the alias of a target S3-compatible host.
Replace TGTPATH with the path to the object on the target S3-compatible host. Omit the object name to use the SRCPATH object name.

Requires Versioning

mc cp requires bucket versioning to use this feature. Use mc version to enable versioning on a bucket.

Add a `content-type` Value

Use mc cp --attr to add a content-type value. This command only applies to S3-to-S3 copy.

mc cp --attr="content-type=CONTENT-TYPE" SRCALIAS/SRCPATH TGTALIAS/TGTPATH

Replace CONTENT-TYPE with the desired content type (also called a media type).
Replace SRCALIAS with the alias of a source S3-compatible host.
Replace SRCPATH with the path to the object on the source S3-compatible host.
Replace TGTALIAS with the alias of a target S3-compatible host.
Replace TGTPATH with the path to the object on the target S3-compatible host. Omit the object name to use the SRCPATH object name.

The following example sets a content-type of application/json:

 mc cp data.ndjson --attr="content-type=application/json" myminio/mybucket

Behavior

mc cp verifies all copy operations to object storage using MD5SUM checksums.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with MinIO and AWS S3 for expected functionality and behavior.

MinIO provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While mc commands may work as documented, any such usage is at your own risk.