# mc mv

LLMS index: [llms.txt](/llms.txt)

---

> [!NOTE]
> **Since mcli 20260916:** A failed copy never authorizes source deletion. A successful copy followed by a failed source deletion exits 1 after waiting for deletion results; successfully copied objects are not rolled back. The selected SDK also reports S3 errors embedded in CopyObject HTTP 200 responses. [Release behavior](/compatibility/mcli/#current-release).


<a id="mc-mv"></a>

<a id="command-mc.mv"></a>

## Syntax {#syntax}

The [`mc mv`](#command-mc.mv) command moves an object from source to the target, such as between MinIO deployments *or* between buckets on the same MinIO deployment. [`mc mv`](#command-mc.mv) also supports moving objects between a local filesystem and MinIO.

You can also use [`mc mv`](#command-mc.mv) against the local filesystem to produce similar results to the `mv` commandline tool.

**EXAMPLE**

The following command moves objects from the `mydata` bucket to the `archive` bucket on the `myminio` MinIO deployment:

```shell
mc mv --recursive myminio/mydata myminio/archive
```

**SYNTAX**

The command has the following syntax:

```shell
mc [GLOBALFLAGS] mv         \
[--attr "string"]           \
[--disable-multipart]       \
[--enc-kms "string"]        \
[--enc-s3 "string"]         \
[--enc-c "string"]          \
[--limit-download string]   \
[--limit-upload string]     \
[--newer-than "string"]     \
[--older-than "string"]     \
[--preserve]                \
[--recursive]               \
[--storage-class "string"]  \
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 {#parameters}

##### `SOURCE` {#mc.mv.SOURCE}

*mc-cmd*

##### `:required:` {#mc.mv.-required}

*mc-cmd*

The object or objects to move.

> For moving an object from a MinIO bucket, specify the [alias](/reference/minio-mc/mc-alias-set/#alias) and the full path to the object(s) (e.g. bucket and path to objects). For example:
>
> ```shell
> mc mv play/mybucket/object.txt play/myotherbucket/object.txt
> ```
>
> For moving an object from a local filesystem, specify the full path to that object. For example:
>
> ```shell
> mc mv ~/mydata/object.txt play/mybucket/object.txt
> ```
>
> Specify multiple `SOURCE` paths to move multiple objects to the specified [`TARGET`](#mc.mv.TARGET). [`mc rm`](/reference/minio-mc/mc-rm/#command-mc.rm) treats the *last* specified alias or filesystem path as the `TARGET`. For example:
>
> ```shell
> mc mv ~/mydata/object.txt play/mydata/otherobject.txt myminio/mydata
> ```
>
> If you specify a directory or bucket to [`SOURCE`](#mc.mv.SOURCE), you must also specify [`--recursive`](#mc.mv.-recursive) to recursively move the contents of that directory. If you omit the [`--recursive`](#mc.mv.-recursive) argument, [`mv`](#command-mc.mv) only moves objects in the top level of the specified directory or bucket.

##### `TARGET` {#mc.mv.TARGET}

*mc-cmd*

*Required*

The full path to the bucket to which the command moves the object(s) at the specified [`SOURCE`](#mc.mv.SOURCE). Specify the [alias](/reference/minio-mc/mc-alias-set/#alias) of a configured S3 service as the prefix to the [`TARGET`](#mc.mv.TARGET) path.

For moving an object from MinIO, specify the [alias](/reference/minio-mc/mc-alias-set/#alias) and hte full path to the object(s) (e.g. bucket and path to objects). For example:

```shell
mc mv play/mybucket/object.txt play/myotherbucket/object.txt
```

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

```shell
mc mv ~/mydata/object.txt play/mybucket/object.txt
```

The `TARGET` object name can differ from the `SOURCE` to “rename” the object as part of the move operation.

If running [`mc mv`](#command-mc.mv) with the [`--recursive`](#mc.mv.-recursive) option, [`mc mv`](#command-mc.mv) treats the `TARGET` as the bucket prefix for all objects at the `SOURCE`.

##### `--attr` {#mc.mv.-attr}

*mc-cmd*

*Optional*

Add custom metadata for the object. Separate pairs with semicolons and quote the argument, for example `--attr 'key1=value1;key2=value2;key3=value3'`. Starting with [mcli 20261109](/blog/release/mcli-20261109/), empty entries (including trailing or repeated semicolons) are accepted while inputs containing no key/value entry still fail, and [mcli](/compatibility/mcli/#current-release) rejects malformed attributes before copying or deleting any source.

##### `--disable-multipart` {#mc.mv.-disable-multipart}

*mc-cmd*

*Optional*

Disables the multipart upload feature.

Multipart upload breaks an object into a set of separate parts. Each part uploads individually and in any order. If any individual part upload fails, MinIO retries that part without affecting the other parts. After upload completes, the parts combine to restore the original object.

MinIO recommends using multipart upload for any object larger than 100 MB. For more information on multipart upload, refer to the [Amazon S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html)

##### `--enc-kms` {#mc.mv.-enc-kms}

*mc-cmd*

Encrypt or decrypt objects using server-side [SSE-KMS encryption](/administration/server-side-encryption/#minio-sse) with client-managed keys.

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

<table>
  <tbody>
    <tr>
      <td><p><code>KEY</code></p></td>
      <td><p>The full path to the object as <code>alias/bucket/path/object.ext</code>.</p><p>You can specify only the top-level path to use a single encryption key for all operations in that path.</p></td>
    </tr>
    <tr>
      <td><p><code>VALUE</code></p></td>
      <td><p>Specify an existing data key on the external KMS.</p><p>See the <a href="/reference/minio-mc-admin/mc-admin-kms-key/#mc.admin.kms.key.create"><code>mc admin kms key create</code></a> reference for creating data keys.</p></td>
    </tr>
  </tbody>
</table>

For example:

```shell
--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:

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

##### `--enc-s3` {#mc.mv.-enc-s3}

*mc-cmd*

*Optional*

Encrypt or decrypt objects using server-side [SSE-S3 encryption](/administration/server-side-encryption/#minio-sse) with KMS-managed keys. Specify the full path to the object as `alias/bucket/prefix/object`.

For example:

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

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

```shell
--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:

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

##### `--enc-c` {#mc.mv.-enc-c}

*mc-cmd*

*Optional*

Encrypt or decrypt objects using server-side [SSE-C encryption](/administration/server-side-encryption/#minio-sse) with client-managed keys.

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

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

- `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:

```shell
# 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:

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

> [!NOTE]
> **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.

##### `--limit-download` {#mc.mv.-limit-download}

*mc-cmd*

*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:

```text
--limit-download 1G
```

If not specified, MinIO uses an unlimited download rate.

##### `--limit-upload` {#mc.mv.-limit-upload}

*mc-cmd*

*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:

```text
--limit-upload 1G
```

If not specified, MinIO uses an unlimited upload rate.

##### `--newer-than` {#mc.mv.-newer-than}

*mc-cmd*

*Optional*

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

Defaults to `0` (all objects).

##### `--older-than` {#mc.mv.-older-than}

*mc-cmd*

*Optional*

Remove 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` {#mc.mv.-preserve}

*mc-cmd*

*Optional*

Preserve file system attributes and bucket policy rules of the [`SOURCE`](#mc.mv.SOURCE) directories, buckets, and objects on the [`TARGET`](#mc.mv.TARGET) bucket(s).

##### `--recursive, r` {#mc.mv.-recursive}

*mc-cmd*

*Optional*

Recursively move the contents of each bucket or directory [`SOURCE`](#mc.mv.SOURCE) to the [`TARGET`](#mc.mv.TARGET) bucket.

##### `--storage-class` {#mc.mv.-storage-class}

*mc-cmd*

*Optional*

Set the storage class for the new object(s) on the [`TARGET`](#mc.mv.TARGET).

See the Amazon documentation on [Storage Classes](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html) for more information on S3 storage classses.

### Global Flags {#global-flags}

This command supports any of the [global flags](/reference/minio-mc/#minio-mc-global-options).

## Examples {#examples}

### Move Files from Filesystem to S3-Compatible Host {#move-files-from-filesystem-to-s3-compatible-host}

```shell
mc mv [--recursive] FILEPATH ALIAS/PATH
```

- Replace [`FILEPATH`](#mc.mv.SOURCE) with the full file path to the file to move.

  If specifying the path to a directory, include the [`--recursive`](#mc.mv.-recursive) flag.

  [`mc mv`](#command-mc.mv) *removes* the files from the source after successfully moving it to the destination.
- Replace [`ALIAS`](#mc.mv.TARGET) with the [`alias`](/reference/minio-mc/mc-alias/#command-mc.alias) of a configured S3-compatible host.
- Replace [`PATH`](#mc.mv.TARGET) with the destination bucket.

### Move a File from Filesystem to S3-Compatible Host with Custom Metadata {#move-a-file-from-filesystem-to-s3-compatible-host-with-custom-metadata}

Use [`mc mv`](#command-mc.mv) with the [`--attr`](#mc.mv.-attr) option to set custom attributes on file(s).

```shell
mc mv --attr "ATTRIBUTES" FILEPATH ALIAS/PATH
```

- Replace [`FILEPATH`](#mc.mv.SOURCE) with the full file path to the file to move. [`mc mv`](#command-mc.mv) *removes* the file from the source after successfully moving it to the destination.
- Replace [`ALIAS`](#mc.mv.TARGET) with the [`alias`](/reference/minio-mc/mc-alias/#command-mc.alias) of a configured S3-compatible host.
- Replace [`PATH`](#mc.mv.TARGET) with the destination bucket.
- Replace [`ATTRIBUTES`](#mc.mv.-attr) with one or more comma-separated key-value pairs `KEY=VALUE`. Each pair represents one attribute key and value.

### Move Bucket Between S3-Compatible Services {#move-bucket-between-s3-compatible-services}

```shell
 mc mv --recursive SRCALIAS/SRCPATH TGTALIAS/TGTPATH
```

- Replace [`SRCALIAS`](#mc.mv.SOURCE) with the [`alias`](/reference/minio-mc/mc-alias/#command-mc.alias) of a configured S3-compatible host.
- Replace [`SRCPATH`](#mc.mv.SOURCE) with the path to the bucket. [`mc mv`](#command-mc.mv) *removes* the bucket and its contents from the source after successfully moving it to the destination.
- Replace [`TGTALIAS`](#mc.mv.TARGET) with the [`alias`](/reference/minio-mc/mc-alias/#command-mc.alias) of a configured S3-compatible host.
- Replace [`TGTPATH`](#mc.mv.TARGET) with the path to the bucket.

### Move File to S3-Compatible Host with Specific Storage Class {#move-file-to-s3-compatible-host-with-specific-storage-class}

Use [`mc mv`](#command-mc.mv) with the [`--storage-class`](#mc.mv.-storage-class) option to set the storage class on the destination S3-compatible host.

```shell
mc mv --storage-class CLASS FILEPATH ALIAS/PATH
```

- Replace [`CLASS`](#mc.mv.-storage-class) with the storage class to associate to the files.
- Replace [`FILEPATH`](#mc.mv.SOURCE) with the full file path to the file to move. [`mc mv`](#command-mc.mv) *removes* the file from the source after successfully moving it to the destination.
- Replace [`ALIAS`](#mc.mv.TARGET) with the [`alias`](/reference/minio-mc/mc-alias/#command-mc.alias) of a configured S3-compatible host.
- Replace [`PATH`](#mc.mv.TARGET) with the destination bucket.
- Replace [`ATTRIBUTES`](#mc.mv.-attr) with one or more comma-separated key-value pairs `KEY=VALUE`. Each pair represents one attribute key and value.

  > mc mv –storage-class REDUCED_REDUNDANCY myobject.txt play/mybucket

## Behavior {#behavior}

### Partial failures and endpoint identity {#partial-failures}

Starting with [mcli 20261109](/blog/release/mcli-20261109/) ([compatibility notes](/compatibility/mcli/#current-release)), a source preparation error makes the command exit nonzero while independent sources, including later arguments, continue. Multi-source moves evaluate source-to-target routing per source item (`URLs.SourceAlias`), and explicit `--tags` apply across server-side copies, streaming copies, and `--preserve` runs. Successfully moved sources are deleted; there is no rollback. JSON start-record `totalCount` and `totalSize` values are cumulative prepared counts and bytes, not final totals or proof of completion. Check the final exit status and error records.

The move guard rejects identical resolved objects and ambiguous same-bucket/key moves through endpoints sharing a scheme, port and IP, including `--resolve` mappings. Shared-IP virtual hosts can therefore be rejected. Establish that their stores are independent before copying, verifying and removing explicitly; reading matching bytes through two aliases does not prove independence. Different addresses, ports, proxy routing, virtual-host addressing or changing DNS can hide a shared backend. Use a consistent endpoint URL for aliases to the same store. For a proxied endpoint, local DNS failure leaves its address unknown rather than rejecting the move. Proxy selection follows the transport rules, including `NO_PROXY`; an unresolved direct endpoint still fails.

### Object Names on Move {#object-names-on-move}

MinIO uses the [`SOURCE`](#mc.mv.SOURCE) object name when moving the object to the [`TARGET`](#mc.mv.TARGET) if no explicit target object name is specified.

You can specify a different object name for the [`TARGET`](#mc.mv.TARGET) with the same object path to “rename” an object. For example:

```shell
mc mv play/mybucket/object.txt play/mybucket/myobject.txt
```

For recursive move operations ([`mc mv --recursive`](#mc.mv.-recursive)), MinIO treats the `TARGET` path as a prefix for objects on the `SOURCE`.

### Checksum Verification {#checksum-verification}

[`mc mv`](#command-mc.mv) verifies all move operations to object storage using MD5SUM checksums.

### MinIO Trims Empty Prefixes on Object Removal {#minio-trims-empty-prefixes-on-object-removal}

[`mc mv`](#command-mc.mv) relies on the [`mc`](/reference/minio-mc/#command-mc) removal API for deleting objects. As part of removing the last object in a bucket prefix, [`mc`](/reference/minio-mc/#command-mc) also recursively removes each empty part of the prefix up to the bucket root. [`mc`](/reference/minio-mc/#command-mc) only applies the recursive removal to prefixes created *implicitly* as part of object write operations - that is, the prefix was not created using an explicit directory creation command such as [`mc mb`](/reference/minio-mc/mc-mb/#command-mc.mb).

For example, consider a bucket `photos` with the following object prefixes:

- `photos/2021/january/myphoto.jpg`
- `photos/2021/february/myotherphoto.jpg`
- `photos/NYE21/NewYears.jpg`

`photos/NYE21` is the *only* prefix explicitly created using [`mc mb`](/reference/minio-mc/mc-mb/#command-mc.mb). All other prefixes were *implicitly* created as part of writing the object located at that prefix.

If an [`mc`](/reference/minio-mc/#command-mc) command removes `myphoto.jpg`, the removal API automatically trims the empty `/january` prefix. If a subsequent [`mc`](/reference/minio-mc/#command-mc) command removes `myotherphoto.jpg`, the removal API automatically trims both the `/february` prefix *and* the now-empty `/2021` prefix. If an [`mc`](/reference/minio-mc/#command-mc) command removes `NewYears.jpg`, the `/NYE21` prefix remains in place since it was *explicitly* created.

If using [`mc mv`](#command-mc.mv) for operations on a filesystem, [`mc`](/reference/minio-mc/#command-mc) applies this same behavior by recursively trimming empty directory paths up to the root. However, the [`mc`](/reference/minio-mc/#command-mc) remove API cannot distinguish between an explicitly created directory path and an implicitly created one. If [`mc mv`](#command-mc.mv) deletes the last object at a filesystem path, [`mc`](/reference/minio-mc/#command-mc) recursively deletes all empty directories within that path up to the root as part of the removal operation.

### S3 Compatibility {#s3-compatibility}

SILO is the supported server for PGSTY mcli; compatibility with upstream MinIO and other S3 services is [best effort](/reference/minio-mc/#command-mc).

The HTTP-200 CopyObject repair applies when mcli selects a single CopyObject: objects smaller than 64 MiB or explicit `--disable-multipart`. Larger copies normally use ComposeObject; this fix does not substitute for separate evidence for that path.