Welcome to the upcoming version of the MinIO Documentation! The content on this page is under active development and may change at any time. If you can't find what you're looking for, check our legacy documentation. Thank you for your patience.

Bucket Replication

MinIO supports server-side and client-side replication of objects between source and destination buckets.

Server-Side Bucket Replication

Configure per-bucket rules for automatically synchronizing objects between buckets within the same MinIO cluster or between two independent MinIO Clusters. MinIO applies rules as part of object write operations (e.g. PUT) and automatically synchronizes new objects and object mutations, such as new object versions or changes to object metadata.

MinIO server-side bucket replication only supports MinIO clusters for the remote replication target.

Client-side Bucket Replication

Use the mc mirror process to synchronize objects between buckets within the same S3-compatible cluster or between two independent S3-compatible clusters. Client-side replication using mc mirror supports MinIO-to-S3 and similar replication configurations.

Server-Side Bucket Replication

MinIO server-side bucket replication is an automatic bucket-level configuration that synchronizes objects between a source and destination bucket. MinIO server-side replication requires the source and destination bucket be MinIO clusters. The source and destination bucket may be the same MinIO cluster or two independent MinIO clusters.

For each write operation to the bucket, MinIO checks all configured replication rules for the bucket and applies the matching rule with highest configured priority. MinIO synchronizes new objects and object mutations, such as new object versions or changes to object metadata. This includes metadata operations such as enabling or modifying object locking or retention settings.

MinIO server-side bucket replication is functionally similar to Amazon S3 replication while adding the following MinIO-only features:

  • Source and destination bucket names can match, supporting site-to-site use cases such as Splunk or Veeam BC/DR.

  • Simplified implementation than S3 bucket replication configuration, removing the need to configure settings like AccessControlTranslation, Metrics, and SourceSelectionCriteria.

  • Active-Active (Two-Way) replication of objects between source and destination buckets.

  • Multi-Site replication of objects between three or more MinIO deployments (New in RELEASE.2021-09-23T04-46-24Z).

Replication Process

MinIO uses a replication queuing system with multiple concurrent replication workers operating on that queue. MinIO continuously works to replicate and remove objects from the queue while scanning for new unreplicated objects to add to the queue.

MinIO sets the X-Amz-Replication-Status metadata field according to the replication state of the object:

Replication State



The object has not yet been replicated. MinIO applies this state if the object meets one of the configured replication rules on the bucket. MinIO continuously scans for PENDING objects not yet in the replication queue and adds them to the queue as space is available.

For multi-site replication, objects remain in the PENDING state until replicated to all configured remotes for that bucket or bucket prefix.


The object has successfully replicated to the remote cluster.


The object failed to replicate to the remote cluster.

MinIO continuously scans for FAILED objects not yet in the replication queue and adds them to the queue as space is available.


The object is itself a replica from a remote source.

MinIO ignores REPLICA objects, including any metadata-only changes to that object. MinIO does not support AWS replica modification sync at this time.

The replication process generally has one of the following flows:



Synchronous vs Asynchronous Replication

MinIO supports specifying either asynchronous (default) or synchronous replication for a given remote target.

With the default asynchronous replication, MinIO completes the originating PUT operation before placing the object into a replication queue. The originating client may therefore see a successful PUT operation before the object is replicated. While this may result in stale or missing objects on the remote, it mitigates the risk of slow write operations due to replication load.

With synchronous replication, MinIO attempts to replicate the object prior to completing the originating PUT operation. MinIO returns a successful PUT operation whether or not the replication attempts succeeds. While this may result in more reliable synchronization between the source and remote target, it may also increase the time of each write operation due to replication load.

You must explicitly enable synchronous replication when configuring the remote target target using the mc admin bucket remote add command with the --sync flag.


The mc replicate resync command can reset replication synchronization for a remote target. The resynchronization process attempts to queue all objects on the source bucket regardless of their replication status. Resynchronization primarily supports recovery after partial or total loss of a remote replication target.

Initiating resynchronization on a bucket uses the same core replication scanner and queue system for detecting and synchronizing objects. MinIO does not prioritize objects in the target bucket, nor does it empty or otherwise modify the queue to favor objects in the target bucket. MinIO skips synchronizing those objects whose remote copy exactly match the source, including object metadata.

mc replicate resync operates at the bucket level and does not support prefix-level granularity. Initiating resynchronization on a large bucket may result in a significant increase in replication-related load and traffic. Use this command with caution and only when necessary.

Replication Behavior

Replication of Delete Operations

MinIO supports replicating delete operations, where MinIO synchronizes deleting specific object versions and new delete markers. Delete operation replication uses the same replication process as all other replication operations.

MinIO only replicates explicit client-driven delete operations. MinIO does not replicate objects deleted due to lifecycle management expiration rules.

For delete marker replication, MinIO begins the replication process after a delete operation creates the delete marker. MinIO uses the X-Minio-Replication-DeleteMarker-Status metadata field for tracking delete marker replication status. In active-active replication configurations, MinIO may produce duplicate delete markers if both clusters concurrently create a delete marker for an object or if one or both clusters were down before the replication event synchronized.

For replicating the deletion of a specific object version, MinIO marks the object version as PENDING until replication completes. Once the remote target deletes that object version, MinIO deletes the object on the source. While this process ensures near-synchronized version deletion, it may result in listing operations returning the object version after the initial delete operation. MinIO uses the X-Minio-Replication-Delete-Status for tracking delete version replication status.

MinIO requires explicitly enabling versioned deletes and delete marker replication . Use the mc replicate add --replicate field to specify both or either delete and delete-marker to enable versioned deletes and delete marker replication respectively. To enable both, specify both strings using a comma separator delete,delete-marker.

Replication of Existing Objects

MinIO by default does not enable existing object replication. Objects created before replication was configured or while replication is disabled are not synchronized to the target deployment. Starting with mc RELEASE.2021-06-13T17-48-22Z and minio RELEASE.2021-06-07T21-40-51Z, MinIO supports enabling replication of existing objects in a bucket.

Enabling existing object replication marks all objects or object prefixes that satisfy the replication rules as eligible for synchronization to the source cluster, even if those objects were created prior to configuring or enabling replication. You can enable existing object replication while configuring or modifying a replication rule:

  • For new replication rules, include "existing-objects" to the list of replication features specified to mc replicate add --replicate.

  • For existing replication rules, add "existing-objects" to the list of existing replication features using mc replicate edit --replicate. You must specify all desired replication features when editing the replication rule.

Enabling existing object replication does not increase the priority of objects pending replication. MinIO uses the same core replication scanner and queue system for detecting and synchronizing objects regardless of the enabled replication feature. The time required to fully synchronize a bucket depends on a number of factors, including but not limited to the current cluster replication load, overall cluster load, and the size of the namespace (all objects in the bucket).

MinIO does not synchronize existing unversioned objects. Specifically, the bucket must have versioning enabled when the object was created. You can use the mc cp command to create a “versioned” copy of that object. Once that object replicates successfully, you can delete the unversioned object (versionid = null).

MinIO existing object replication implements functionality similar to AWS: Replicating existing objects between S3 buckets without the overhead of contacting technical support.

Client-Side Bucket Replication

The mc command mc mirror supports watching a source bucket and automatically replicating objects to a destination bucket.