Setting a reliable browser download filename is mostly a matter of sending the right HTTP response headers. This guide explains how to use Content-Disposition, choose between inline and attachment delivery, support UTF-8 filenames, verify the result with command-line tools, and avoid common security and compatibility mistakes.
Overview
The Content-Disposition response header tells a user agent how to handle a response. For downloadable files, the usual value is attachment. A filename parameter then suggests the name the browser should use when saving the file:
Content-Disposition: attachment; filename="report.pdf"
Use inline when the resource can reasonably be displayed in the browser, such as an image or PDF that users may preview:
Content-Disposition: inline; filename="preview.pdf"
This header is a filename suggestion, not a way to control a user’s filesystem. Browsers, operating systems, download settings, existing files, and user actions can affect the final saved name. The server should also send an accurate Content-Type; the MIME type and the filename extension solve different parts of the delivery problem. See the MIME types and file extensions reference when checking both values.
For names containing accents or other non-ASCII characters, use filename* with UTF-8 and percent encoding. A practical header includes an ASCII fallback as well:
Content-Disposition: attachment; filename="resume.pdf"; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf
The fallback helps clients that do not process filename*, while the extended parameter preserves the intended Unicode name where supported. Generate both values from a trusted, normalized display name rather than inserting raw user input into a header.
| Goal | Recommended header | Check |
|---|---|---|
| Force a save dialog or download behavior | attachment; filename="file.ext" | Confirm the response is not being replaced by a redirect or HTML error. |
| Allow browser preview | inline; filename="file.ext" | Verify the media type is suitable for inline handling. |
| Support a Unicode filename | ASCII filename plus UTF-8 filename* | Test the actual browsers and clients used by your application. |
| Serve a cloud-stored object with a download name | Set the provider’s response-content-disposition option or metadata | Inspect the final URL response, including redirects and signed parameters. |
Checklist by scenario
Standard ASCII filename
- Choose
attachmentfor a download orinlinefor a preview. - Use a quoted filename when it contains spaces or punctuation that could otherwise be parsed ambiguously.
- Keep the name descriptive, such as
invoice-2026-04.pdf, and include the correct extension. - Send the correct
Content-Typeand, where appropriate, a reliableContent-Length.
Unicode or localized filename
- Normalize the display name before creating the header.
- Remove control characters, including carriage returns and line feeds.
- Create a conservative ASCII fallback for
filename. - Encode the original name as UTF-8 percent-encoded data in
filename*. - Test names with spaces, accents, non-Latin scripts, emoji, and long text if those cases matter to your users.
API or file-download endpoint
- Return the file response only after authorization and access checks complete.
- Set headers before writing the response body.
- Make sure errors do not produce a successful file status with an HTML or JSON body.
- Check whether a framework, reverse proxy, or middleware overwrites
Content-Disposition. - Test range requests and caching behavior if large files or resumable downloads are supported.
For an upload or download API, verify the complete response rather than only the application code. The cURL and Postman API testing guide can help structure repeatable request checks.
Cloud storage or signed URL
Object storage services commonly expose a response-header override or a metadata field for download behavior. The exact parameter name and signing rules depend on the provider and SDK. Set the value through the provider’s documented API, then inspect the final HTTP response. A header added by your application may not survive a redirect to storage, and a signed URL may become invalid if a response parameter is changed after signing.
What to double-check
Header construction
Do not concatenate unchecked filenames into a response header. Reject or remove CR, LF, null characters, path separators, and other characters that have no place in a download label. Treat the value as a label, not a filesystem path. Never use a submitted filename to select a server-side path without separate validation and authorization.
Keep the server-side storage key separate from the client-facing filename. A safe internal identifier can map to a friendly name such as project-export.csv without exposing directory structure or allowing path traversal.
Encoding and fallback behavior
filename is intended for the traditional fallback value, while filename* carries a character-set declaration and percent-encoded value. Avoid putting raw non-ASCII text into the fallback and avoid assuming that every client handles duplicate parameters identically. If you need broad compatibility, test the exact header in the browsers, mobile clients, desktop applications, and automated consumers that matter to the product.
Verification with cURL
Use a header-only request to see what the endpoint actually returns:
curl -I -L https://example.com/download/42
The -I option requests headers and -L follows redirects. For an endpoint that requires a method or authentication, use a request closer to production:
curl -L -D response-headers.txt -o downloaded-file \
-H 'Authorization: Bearer REDACTED' \
https://example.com/api/files/42
Review every response in a redirect chain, confirm the final status, and compare the declared media type with the downloaded content. Do not paste live access tokens or private download URLs into public debugging tools or issue reports.
Framework response APIs
Most web frameworks provide a download helper that sets some combination of the disposition, content type, and filename. Prefer that helper when it correctly handles encoding and escaping, but inspect the generated response in an integration test. If setting the header manually, use the framework’s header API rather than writing raw response text.
// Express-style example
res.attachment('report.pdf');
res.type('application/pdf');
res.send(fileBuffer);
The method names differ across platforms, so treat this as a pattern rather than a drop-in implementation. Confirm how your framework handles Unicode names, caching, range responses, and errors.
Common mistakes
- Using only a URL query parameter. A parameter such as
?filename=report.pdfhas no universal browser meaning. SendContent-Dispositionin the response. - Forgetting quotes. An unquoted name with spaces or special punctuation may be parsed inconsistently. Quote the fallback value and escape it according to your framework’s header utilities.
- Using a filesystem path as the filename. The browser needs a display name, not
/var/data/customer/exports/file.pdf. Exposing paths also creates unnecessary information leakage. - Trusting the extension. A name ending in
.pdfdoes not make arbitrary content a PDF. Validate uploads and serve the actual content with appropriate security controls. See the file upload security checklist. - Testing only a successful local response. Proxies, redirects, authentication failures, object storage, and production middleware can change headers or return a different body.
- Assuming a download is automatically safe. Content-Disposition influences handling, but it does not replace content validation, access control, malware scanning where appropriate, or safe browser-facing response policies.
- Ignoring accessibility and user expectations. Use a meaningful name that identifies the document and its purpose. A clear filename complements an accessible upload and download flow.
When to revisit
Keep this checklist with the endpoint or storage integration and revisit it whenever the workflow changes. The most useful review points are:
- when moving files between local storage, a CDN, and object storage;
- when changing framework versions, HTTP middleware, SDKs, or reverse-proxy configuration;
- when adding localized filenames or new client platforms;
- when a browser or desktop client reports an unexpected saved name;
- when security testing identifies header injection, path handling, content-type, or authorization issues;
- before a seasonal export, reporting cycle, or other high-volume download period.
Before release, run one automated test for the ASCII case, one for a Unicode name, one for a redirect or signed URL if applicable, and one for an authorization failure. Capture status, content type, disposition, and a safe sample of the final filename. This small regression check makes browser download behavior easier to maintain as the surrounding tools and workflows evolve.