Specify object download names using response-content-disposition or Content-Disposition - Object Storage Service

OSS object keys are immutable and often non-descriptive — for example, a UUID like a3f2c1d0-.... To control what filename appears when a user downloads an object, use one of two approaches:

Signed URL with `response-content-disposition` — overrides the filename for that specific download only, without modifying the object's metadata.
`Content-Disposition` metadata header — sets a default filename that applies to all downloads of the object.

How download filenames are resolved

OSS determines the downloaded filename in the following priority order:

Priority	Source	Applies when
1 (highest)	`response-content-disposition` parameter in the signed URL	The signed URL contains the parameter
2	`Content-Disposition` object metadata header	The signed URL does not contain the parameter
3 (fallback)	OSS object key	Neither of the above is set

Set a filename for a specific download using a signed URL

A signed URL grants time-limited access to a private object. Add the response-content-disposition parameter to the URL to specify the downloaded filename — the object's metadata is not modified, so other download methods are unaffected.

Common use cases:

Object sharing: Share an object without exposing its internal object key. The recipient sees a meaningful filename.
Personalized downloads: Generate per-user signed URLs with custom filenames (for example, by username or order number).
Preview and testing: Let reviewers download an object under a test-friendly name without altering the default.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket containing the target object
The oss:GetObject permission. For details, see Attach a custom policy to a RAM user

Usage notes

response-content-disposition applies to the signed URL only — it does not affect other downloads of the same object.
URL-encode object names to prevent errors caused by special characters.
Signed URLs expire after their validity period. Factor the expiration time into how you share URLs with users.
If the object also has a Content-Disposition metadata header, the signed URL parameter takes precedence and the metadata header is ignored.

Sample code

The following Python example generates a signed URL that causes the object to download with the filename desired-filename.txt.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from urllib.parse import quote

# Load credentials from environment variables.
# Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Replace <bucket_name> with your bucket name.
# Replace the endpoint with the endpoint for your bucket's region.
# Example: https://oss-cn-hangzhou.aliyuncs.com for the China (Hangzhou) region.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Full path of the object in the bucket. Do not include the bucket name.
object_name = 'exampledir/exampleobject.txt'

# The filename shown to the user when they download the object.
# URL-encode the name to handle special characters.
download_filename = quote('desired-filename.txt')

# Save the object as the specified filename during download.
params = {'response-content-disposition': f'attachment; filename="{download_filename}"'}

# Generate a signed URL valid for 3,600 seconds.
# slash_safe=True prevents OSS from treating forward slashes in the
# object path as escape characters.
url = bucket.sign_url('GET', object_name, 3600, params=params, slash_safe=True)

print('Signed URL:', url)

For examples in other languages, see Share objects with object URLs.

Set a filename for all downloads by updating object metadata

The Content-Disposition metadata header sets the default filename for every download of an object. This applies to all requests that do not include the response-content-disposition parameter.

Common use cases:

Long-term sharing: The object is downloaded repeatedly and should always appear with the same filename.
Document and resource libraries: Files in public libraries have consistent, descriptive names for easy identification and archiving.
Versioned content: Update an object in place (same key, new content) and keep a stable, human-readable filename across all downloads.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket containing the target object
The oss:PutObject permission. For details, see Attach a custom policy to a RAM user

Usage notes

URL-encode the filename in the Content-Disposition value to handle special characters.
Updating the header overwrites all object metadata. To preserve other existing headers, fetch the current metadata first, update Content-Disposition, and then write the full updated set.
Use update_object_meta instead of PutObject to update metadata without re-uploading the object, which avoids accidental data overwrite.

Sample code

The following Python example sets the Content-Disposition header so the object downloads with the filename desired-filename.txt.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from urllib.parse import quote

# Load credentials from environment variables.
# Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Replace <bucket_name> with your bucket name.
# Replace the endpoint with the endpoint for your bucket's region.
# Example: https://oss-cn-hangzhou.aliyuncs.com for the China (Hangzhou) region.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Full path of the object in the bucket. Do not include the bucket name.
object_name = 'exampledir/exampleobject.txt'

# The filename shown to the user when they download the object.
# URL-encode the name to handle special characters.
download_filename = quote('desired-filename.txt')

# Set the filename shown to users for all future downloads of this object.
#
# Note: update_object_meta overwrites ALL existing metadata headers.
# To keep other headers intact, fetch them first with bucket.get_object_meta(),
# merge your changes, and then call update_object_meta with the full set.
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

For examples in other languages, see Manage object metadata.

What's next

Share objects with object URLs — generate and distribute signed URLs
Manage object metadata — update other metadata headers
Attach a custom policy to a RAM user — configure the required permissions