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.

mc rm

Description

The mc rm command removes objects on a target S3-compatible service. To completely remove a bucket, use mc rb instead.

Deleting Bucket Contents

Using mc rm to remove all contents in a bucket does not delete the bucket itself. Any configurations associated to the bucket remain in place, such as default object lock settings.

To completely remove a bucket, use mc rb instead of mc rm.

MinIO Trims Empty Prefixes on Object Removal

mc rm relies on the mc removal API for deleting objects. As part of removing the last object in a bucket prefix, mc also recursively removes each empty part of the prefix up to the bucket root. 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.

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. All other prefixes were implicitly created as part of writing the object located at that prefix.

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

If using mc rm for operations on a filesystem, mc applies this same behavior by recursively trimming empty directory paths up to the root. However, the mc remove API cannot distinguish between an explicitly created directory path and an implicitly created one. If mc rm deletes the last object at a filesystem path, mc recursively deletes all empty directories within that path up to the root as part of the removal operation.

Examples

Remove a Single Object

mc rm ALIAS/PATH
  • Replace ALIAS with the alias of a configured S3-compatible service.

  • Replace PATH with the path to the object.

Recursively Remove a Bucket’s Contents

Use mc rm with the --recursive and --force options to recursively remove a bucket’s contents.

mc rm --recursive --force ALIAS/PATH
  • Replace ALIAS with the alias of a configured S3-compatible service.

  • Replace PATH with the path to the bucket.

This operation does not remove the bucket. Use mc rb to remove the bucket along with all contents and associated configurations.

Remove All Incomplete Upload Files for an Object

Use mc rm with the --incomplete option to remove incomplete upload files for an object.

mc rm --recursive --force ALIAS/PATH
  • Replace ALIAS with the alias of a configured S3-compatible service.

  • Replace PATH with the path to the object.

Removing incomplete upload files prevents resuming the upload using the mc mv --continue or mc cp --continue commands.

Roll Object Back To Previous Version

Use mc rm with --versions and --newer-than to remove all object versions newer than the specified duration of time. This effectively “rolls back” the object to its state at that time.

Important

Removing specific versions of an object is a destructive action. You cannot restore the deleted object versions.

mc rm ALIAS/PATH --versions --newer-than DURATION
  • Replace ALIAS with the alias of a configured S3-compatible service.

  • Replace PATH with the path to the object. For example, /mybucket/myobject.

  • Replace DURATION with the number of days in the past from the current host time from which the operation begins removing versions of the object. For example, to remove all versions of the object created in the last 30 days, specify "30d".

Syntax

mc rm has the following syntax:

mc rm [FLAGS] TARGET [TARGET ...]

rm supports the following arguments:

TARGET

REQUIRED

The full path to object to remove. Specify the alias of a configured S3 service as the prefix to the --TARGET path.

For example:

mc rm play/mybucket/object.txt play/mybucket/otherobject.txt

If specifying the path to a bucket or bucket prefix, you must also specify the --recursive and --force arguments. For example:

mc rm --recursive --force play/mybucket/

mc rm --recursive --force play/mybucket/myprefix
--recursive, --r

Recursively remove the contents of each --TARGET bucket or bucket prefix.

If specifying --recursive, you must also specify --force.

Mutually exclusive with mc rm --version-id

--force

Allows running mc rm with any of the following arguments:

--dangerous

Allows running mc rm when the TARGET specifies the root (all buckets) on the S3-compatible service.

--versions

Directs mc rm to operate on all object versions that exist in the bucket.

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

Use --versions and --rewind together to remove all object versions which existed at a specific point in time.

--rewind

Directs mc rm 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 --TARGET be an S3-compatible service that supports Bucket Versioning. For MinIO deployments, use mc version to enable or disable bucket versioning.

--version-id, --vid

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

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

Mutually exclusive with any of the following flags:

--older-than

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).

--newer-than

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).

--incomplete, --I

Remove incomplete uploads for the specified object.

If any --TARGET specifies a bucket, you must also specify --recursive and --force.

--fake

Perform a fake remove operation. Use this operation to perform validate that the mc rm operation will only remove the desired objects or buckets.

--stdin

Read object names or buckets from STDIN.

--encrypt-key

The encryption key to use for performing Server-Side Encryption with Client Keys (SSE-C). Specify comma seperated key-value pairs as KEY=VALUE,....

  • For KEY, specify the S3-compatible service alias and full path to the bucket, including any bucket prefixes. Separate the alias and bucket path with a forward slash \. For example, play/mybucket

  • For VALUE, specify the data key to use for encryption object(s) in the bucket or bucket prefix specified to KEY.

--encrypt-key can use the MC_ENCRYPT_KEY environment variable for populating the list of encryption key-value pairs as an alternative to specifying them on the command line.