Content-Disposition

File downloads and inline rendering are controlled by the Content-Disposition response header, which indicates whether the browser displays content directly or triggers a download dialog.

Table of Contents

Usage
Directives
Example
Troubleshooting
See also

Usage

In a standard HTTP response, the Content-Disposition header controls how the browser presents content to the user. Setting the value to inline tells the browser to render the content directly. Setting the value to attachment triggers a download dialog instead.

This header also plays a role in multipart/form-data responses and form submissions. Each part of a multipart body includes its own Content-Disposition field, identifying the form field name and optional filename for uploaded files. The part boundary is defined in the Content-Type header.

Directives

inline

The inline directive instructs the browser to display the content directly within the page. This is the default behavior for most responses when Content-Disposition is absent.

attachment

The attachment directive triggers a download prompt. The browser presents a "Save As" dialog rather than rendering the content in the viewport.

filename

The filename parameter suggests a default filename for the downloaded file. The value is enclosed in double quotes and follows ASCII encoding rules.

Content-Disposition: attachment; filename="report.pdf"

filename*

The filename* parameter extends filename with support for character encoding beyond ASCII. When both filename and filename* are present, filename* takes priority. This is useful for filenames containing non-ASCII characters.

Content-Disposition: attachment; filename="document.pdf"; filename*=UTF-8''d%C3%B6cument.pdf

form-data

The form-data directive appears in multipart body parts and identifies the content as belonging to a form submission.

name

The name parameter is required within multipart body parts and identifies the form field the part corresponds to.

Example

A server responding with a CSV file download sets attachment and provides a suggested filename. The browser opens a save dialog with "export.csv" pre-filled.

Content-Disposition: attachment; filename="export.csv"

A server displaying a PDF directly in the browser uses inline. The browser renders the PDF in its built-in viewer rather than downloading the file.

Content-Disposition: inline

In a multipart form submission, each part carries its own Content-Disposition field. The name parameter maps the part to the corresponding form field, and filename indicates the original name of an uploaded file.

Content-Disposition: form-data; name="avatar"; filename="photo.jpg"

Troubleshooting

Download and display problems with Content-Disposition typically stem from incorrect directive values or filename encoding mistakes.

File downloads with the wrong filename. The browser uses the filename parameter as the default save name. A missing or malformed filename value causes the browser to fall back to the URL path or a generic name. Ensure the value is enclosed in double quotes: filename="report.pdf". Verify the header with curl -sS -o /dev/null -D- https://example.re/file and check the filename parameter in the response.
Non-ASCII characters in filenames break or display as garbage. The filename parameter supports only ASCII characters. For names with accented letters, CJK characters, or other non-ASCII text, add the filename* parameter using the encoding syntax: filename*=UTF-8''d%C3%B6cument.pdf. Include both filename (ASCII fallback) and filename* (encoded version) for maximum compatibility across browsers.
Browser renders content instead of downloading. Modern browsers honor attachment reliably. When a file renders in the browser anyway, the usual cause is a missing or misspelled Content-Disposition header or an intermediary stripping it. The reverse override is common: browsers download inline content they refuse to render. Setting Content-Type: application/octet-stream alongside attachment forces a download for any file type.
Inline display triggered when download is expected. A missing Content-Disposition header defaults to inline for most content types. The server must explicitly send attachment to trigger a download. In nginx, add add_header Content-Disposition "attachment"; to the relevant location block. In Apache, use Header set Content-Disposition "attachment" within a <Location> or <FilesMatch> directive.
filename vs filename precedence.* When both parameters are present, filename* takes priority in all modern browsers. Older clients that do not support filename* fall back to filename. Always include both parameters. The filename* value must use percent-encoding for special characters: filename*=UTF-8''na%C3%AFve.txt.
Framework-specific download response helpers. Most web frameworks provide built-in methods for setting download headers. Django uses FileResponse with the as_attachment parameter. Express uses res.download(). Flask uses send_file() with as_attachment=True. Rails uses send_data or send_file with a disposition option. These methods handle filename encoding and header formatting, reducing the chance of manual errors.