DeleteDirectory - Delete a directory in OSS - Object Storage Service

Usage notes

Directories support two deletion methods:
- Recursive delete: Deletes all objects and subdirectories in the directory.
- Non-recursive delete: Deletes the directory only if it is empty.
Required permissions differ by deletion method:
- Recursive delete requires the DeleteObject permission on the directory and all objects and subdirectories within it.
  
  For example, recursively deleting desktop/osstest requires DeleteObject permission on the desktop/osstest directory and all its contents.
- Non-recursive delete requires the DeleteObject permission on the directory.
  
  For example, deleting desktop/dir requires DeleteObject permission on the desktop/dir directory.
Recursive deletion may fail if concurrent write requests target the directory.

Request structure

POST /objectName?x-oss-delete HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Header

Type

Required

Description

x-oss-delete-recursive

String

No

Specifies whether to recursively delete a directory.

If you do not specify x-oss-delete-recursive or set x-oss-delete-recursive to false, non-recursive delete is used. Only empty directories can be deleted.
If you set x-oss-delete-recursive to true, recursive delete is used. All objects and subdirectories in the directory are deleted.

Default value: false

x-oss-delete-token

String

No

The object or directory name from which the next deletion starts. Valid only when x-oss-delete-recursive is set to true.

Leave this header empty for the first DeleteDirectory request.

This API operation must also include common request headers such as Host and Date. For more information about common request headers, see Common request headers.

Response headers

The response headers involved in this API operation contain only common response headers. For more information about common response headers involved in this API operation, see Common response headers.

Response elements

Element	Type	Description
DeleteDirectoryResult	Container	Container for the directory deletion result. Parent nodes: none
DirectoryName	String	Name of the deleted directory. Parent nodes: DeleteDirectoryResult
DeleteNumber	String	Number of deleted objects and directories. Parent nodes: DeleteDirectoryResult
NextDeleteToken	String	Name of the next object or directory from which deletion resumes. Parent nodes: DeleteDirectoryResult

Examples

Non-recursive delete

Sample request

POST /desktop/osstest/a?x-oss-delete HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 29 Apr 2021 05:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
Date: Thu, 29 Apr 2021 05:21:12 GMT
Connection: keep-alive
Server: AliyunOSS
<DeleteDirectoryResult>
    <DirectoryName>desktop/osstest/a</DirectoryName>
    <DeleteNumber>1</DeleteNumber>
</DeleteDirectoryResult>

Recursive delete

Sample request

POST /desktop/osstest/a?x-oss-delete HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 29 Apr 2021 05:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-delete-recursive: true

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
Date: Thu, 29 Apr 2021 05:21:12 GMT
Connection: keep-alive
Server: AliyunOSS
<DeleteDirectoryResult>
    <DirectoryName>desktop/osstest/a</DirectoryName>
    <DeleteNumber>100</DeleteNumber>
    <NextDeleteToken>Cg9kZXNrdG9wL29zcy9hLzk-</NextDeleteToken>
</DeleteDirectoryResult>

OSS SDKs

The following OSS SDKs support the DeleteDirectory operation:

Error codes

Error code	HTTP status code	Description
AccessDenied	403	Possible causes: You do not have permission to access the specified bucket. You do not have permission to delete the directory.
NoSuchKey	404	The specified directory does not exist.
FileAlreadyExists	409	Possible causes: The directory is not empty (non-recursive delete). Concurrent write requests conflict with the recursive deletion.
InvalidArgument	400	The x-oss-delete-token value format is invalid.