Encode Non-ASCII Filenames in Content-Disposition Header

To reliably encode non-ASCII filenames like “naïvefile” in the HTTP Content-Disposition: attachment; filename=... header, use the RFC 5987 filename*=UTF-8'' parameter with percent-encoded UTF-8 bytes—think filename*=UTF-8''na%C3%AFvefile.txt. This works across Chrome, Safari, Firefox, Edge, and Opera, but pair it with a fallback ASCII filename="naivefile.txt" for older browsers that ignore the extended param. Modern setups demand this dual approach to avoid garbled downloads or sanitization mishaps.

Contents

• Understanding Content-Disposition Filename Challenges with Non-ASCII Characters
• RFC Standards for Filename Encoding (RFC 5987 and RFC 6266)
• Google Chrome Content Disposition Filename UTF-8 Behavior
• Safari Filename Encoding Quirks and Fixes
• Internet Explorer and Edge Non-ASCII Filename Support
• Firefox and Opera Reliable RFC 5987 Filename Handling
• Cross-Browser Recommended Practices and Code Examples
• Testing Non-ASCII Filenames Like Naïvefile for Downloads
• Sources
• Conclusion

Understanding Content-Disposition Filename Challenges with Non-ASCII Characters

Ever hit a wall where “naïvefile.txt” downloads as “na??vefile.txt” or worse, gets sanitized to “naivefile_txt”? That’s the classic content disposition filename headache with non-ASCII filename characters like ï (U+00EF). HTTP headers are picky—traditional filename expects printable ASCII only, per early specs. Throw in UTF-8 diacritics, Cyrillic (filename кириллица), or even emojis, and browsers start improvising.

The root issue? Legacy parsers choke on raw bytes outside 0x20-0x7E. RFC 6266 clarifies: use filename for safe ASCII fallbacks, but filename* for the real deal. Without proper filename encoding, Safari might raw-decode UTF-8 (pre-version 6), Chrome percent-decodes everything post-RFC, and IE10 mangles it entirely. Quick stat: searches for “content disposition кириллица” spike because Russian devs face this daily.

But here’s the good news—you can fix it predictably. Start with percent-encoding the UTF-8 bytes of your non ascii filename, slap it into filename*, and watch downloads work everywhere.

RFC Standards for Filename Encoding (RFC 5987 and RFC 6266)

Standards evolved to tame this beast. RFC 5987 defines filename*=charset''encoded-value, where charset is “UTF-8” and the value is percent-encoded UTF-8 octets—no quotes inside the encoding.

For “naïvefile.txt”:

1. UTF-8 bytes: 6e 61 C3 AF 76 65 66 69 6c 65 2e 74 78 74
2. Percent-encode non-ASCII: na%C3%AFvefile.txt
3. Header: Content-Disposition: attachment; filename*=UTF-8''na%C3%AFvefile.txt

RFC 6266 builds on it for Content-Disposition, mandating UTF-8 preference and fallback rules. If both filename and filename* appear, filename* wins in compliant UAs—but include filename="naivefile.txt" (transliterated) for IE8-10 or ancient Safari.

Why dual params? Appendix D in RFC 6266 spells it out: maximizes compatibility without breaking old clients. Pro tip: Sanitize slashes (/ → _) to dodge path injection, as some servers parse greedily.

Google Chrome Content Disposition Filename UTF-8 Behavior

Chrome nails chrome content disposition filename handling since v21. It fully supports RFC 5987 filename—decodes filename* perfectly, even percent-decoding filename params if they look encoded.

Tested with “naïvefile.txt”:

Content-Disposition: attachment; filename="na%C3%AFvefile.txt"; filename*=UTF-8''na%C3%AFvefile.txt

Result? Downloads as “naïvefile.txt”. Drop the % in filename, and it still grabs from filename*. Edge case: Chrome ignores ISO-8859-1 entirely now, forcing UTF-8.

From MDN’s browser compat table, Chrome shines on filename utf8. But if you’re serving percent encode filename manually, double-check octets—wrong byte order kills it.

Safari Filename Encoding Quirks and Fixes

Safari’s the wildcard in safari filename encoding. Pre-iOS 7/Mac 10.8 (Safari 5-6), it raw-parses UTF-8 bytes in filename—no percent-decoding. So filename="naïvefile.txt" works if your server sends actual UTF-8 bytes, but filename="na%C3%AFvefile.txt" garbles.

Safari 6+ flips to RFC 5987, prioritizing filename*. Stack Overflow empirics confirm: for cross-version safety,

filename="naivefile.txt"; filename*=UTF-8''na%C3%AFvefile.txt

No % in filename for old Safari, but % everywhere else. Mobile Safari? Same quirks, plus occasional URL bar interference on iOS.

Quick fix: Server-side transliterate (ï → i) for filename, keep full UTF-8 in filename*. Searches for “safari filename encoding” (290 vol.) prove this trips up everyone.

Internet Explorer and Edge Non-ASCII Filename Support

Edge filename encoding matured post-EdgeHTML (Chromium Edge v79+ mirrors Chrome). Legacy IE? Nightmare fuel.

• IE6-9: ASCII filename only; percent-encode manually (e.g., %EF for ï).
• IE10-11: Partial RFC 6266—filename* works, but filename must be percent-encoded UTF-8 too.
• Edge Legacy: Like IE11.
• New Edge: Full rfc 5987 filename example support.

From MDN, IE demands dual params. Example for “naïvefile.txt”:

Content-Disposition: attachment; filename="na%C3%AFvefile.txt"; filename*=utf-8''na%C3%AFvefile.txt

Note lowercase utf-8 tolerance. Without it? “naïvefile” becomes “n___file”. Original filename preservation hinges on this.

Firefox and Opera Reliable RFC 5987 Filename Handling

Firefox attachment filename? Rock-solid since v5. Decodes filename* per RFC, falls back smartly, and even handles filename= utf-8’'* quirks in multipart form-data content-disposition.

Opera follows suit—pre-Chromium (v12-) needed percent-encoded filename, but v15+ is RFC-compliant. Stack Overflow matrix shows both saving “naïvefile.txt” perfectly with:

filename*=UTF-8''na%C3%AFvefile.txt

Firefox bonus: Respects suggested filename hints. Opera? Seamless on downloads. Low drama here—opera filename download just works.

Cross-Browser Recommended Practices and Code Examples

Winning formula for content disposition attachment:

1. Always dual-encode: ASCII/transliterated filename + RFC filename*.
2. Percent-encode UTF-8 strictly (use libraries).
3. Avoid quotes in encoded value.
4. Test download filename in real browsers—not just curl.

PHP example (handles filename кириллица too):

<?php
$filename = 'naïvefile.txt'; // Or 'файл.txt'
$fallback = preg_replace('/[^\x20-\x7e]/', '_', $filename); // naivefile.txt
$encoded = 'UTF-8\'\'' . rawurlencode($filename);

header('Content-Disposition: attachment; filename="' . $fallback . '"; filename*=' . $encoded);
?>

Node.js/Express:

const filename = 'naïvefile.txt';
const fallback = filename.replace(/[^\x20-\x7E]/g, '_');
const encoded = `UTF-8''${encodeURIComponent(filename)}`;

res.set('Content-Disposition', `attachment; filename="${fallback}"; filename*=${encoded}`);

From Jmix blog, modern browsers ignore filename if filename* exists. For base64 filename? Skip it—RFC favors percent.

Testing Non-ASCII Filenames Like Naïvefile for Downloads

Grab a test server. Endpoint: /download?file=naïvefile.txt.

Expected across browsers (2026 compat):

• ✅ Chrome/Edge/Firefox/Opera: “naïvefile.txt”
• ✅ Safari: Same, post-2013

Edge cases:

• Cyrillic: filename*=UTF-8''%D1%84%D0%B0%D0%B9%D0%BB.txt → “файл.txt”
• Emoji: %F0%9F%98%8Dfile.txt → 😀file.txt (Chrome/FF yes, Safari spotty)

Tools: httpbin.org for headers, BrowserStack for matrices. Common pitfall: CDNs stripping filename*. Filename extension stays intact if encoded right.

Sources

1. MDN Web Docs: Content-Disposition — Browser compatibility table for filename and filename* encoding: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition
2. RFC 6266 — Standard for Content-Disposition with filename fallbacks and dual parameters: https://datatracker.ietf.org/doc/html/rfc6266
3. RFC 5987 — Charset and percent-encoding rules for filename*: https://datatracker.ietf.org/doc/html/rfc5987
4. Stack Overflow: Encode Filename Parameter — Empirical browser tests for naïvefile across Chrome/Safari/IE/Firefox: https://stackoverflow.com/questions/93551/how-to-encode-the-filename-parameter-of-content-disposition-header-in-http
5. Jmix Blog: UTF-8 in HTTP Headers — Practical encoding strategies and legacy fallbacks: https://www.jmix.io/blog/utf-8-in-http-headers/

Conclusion

Mastering content disposition filename encoding boils down to RFC 5987’s filename*=UTF-8''percent-encoded plus ASCII fallbacks—your “naïvefile.txt” downloads flawlessly from Chrome to Opera. Skip it, and you’re gambling with garbled non ascii filename chaos. Implement the dual-header pattern today, test rigorously, and own cross-browser reliability. Questions on multipart form-data content-disposition? Dive deeper next.