Content-Disposition
Definition
Two values matter in practice. Content-Disposition: inline asks the browser to render the file in place; Content-Disposition: attachment; filename="report.pdf" asks it to download. With inline, or with no header at all, the browser renders the response if it has a handler for the declared MIME type — a PDF opens in the built-in viewer, a PNG is shown, an HTML page is drawn. With attachment the browser downloads regardless, even for a type it could perfectly well display. The filename parameter sets the suggested save name and is completely independent of the URL, so a resource at /files/a8f3c2d1 can still arrive on disk as report.pdf. Names outside plain ASCII need the extended form, written as filename*=UTF-8''rapport%20final.pdf, which modern browsers prefer when both are present.
Why It Matters
The same bytes at the same address behave in two entirely different ways depending on one header, and the mismatch is usually noticed by customers rather than by the person who published the file. A sales team shares a price list expecting it to open in a tab; the host sends attachment; every recipient gets a save dialog, a fair number cancel it, and the document goes unread. The filename parameter matters just as much on a download link: leave it out and the browser guesses from the last path segment, so a hashed URL saves a file called a8f3c2d1 with no extension and no application willing to open it.
How It Works
The header is set by whatever serves the response, and object stores let you attach it to the object itself so it travels with the file. On arrival the browser checks it first: attachment ends the decision immediately and the download begins. If the value is inline, or the header is absent, the browser falls back to the Content-Type — application/pdf goes to the viewer, image/png to the renderer, application/octet-stream to disk because nothing can display it. There is a security dimension too. Serving a visitor-supplied HTML file inline from your own hostname lets its scripts run against that origin, which is why file hosts either force attachment for such uploads or serve them from a separate domain. The download attribute on an anchor tag does something similar from the client side, but browsers ignore it across origins.
Real-World Example
A consultancy publishes a 6 MB whitepaper through 99helpers at northline-guide.99helpers.site. With the header left at inline the PDF opens in the reader, which is what they want for people arriving from a newsletter. For the version linked from the pricing page they flip the download switch, the object is served with attachment and a filename of northline-pricing-guide.pdf, and the file lands in Downloads under a name that still makes sense a month later.
Common Mistakes
- ✕Leaving a filename with spaces unquoted — some clients truncate the name at the first space and save a file called report instead of report q3 2026.pdf
- ✕Expecting the header to force a download for a link that points at another site — you can only set it on responses you serve yourself
- ✕Setting attachment on a site's index.html, so visiting the address downloads the page rather than showing it
- ✕Using only the plain filename parameter for accented or non-Latin names, which arrive mangled instead of using the extended form
Related Terms
MIME Type
A MIME type, also called a media type or content type, is the short label a server sends to say what kind of data a response contains — text/html, image/png, application/pdf. The browser decides what to do with the bytes based on that label, not on the file name.
Download Link
A download link is an address that makes the browser save a file to disk instead of displaying it in a tab. The behaviour comes from a header on the response or an attribute on the anchor tag, not from anything inside the file.
PDF Hosting
Publishing a .pdf at a web address so it opens in the reader's browser rather than landing in their downloads folder. The header the host sends decides which of those happens.
File Extension
A file extension is the short suffix after the last dot in a file name — .pdf, .png, .html, .woff2 — used as a hint about what the file contains. It is part of the name, never part of the data.
Web Server
The software that listens for HTTP requests and answers them with files or generated responses. Nginx, Apache and Caddy are web servers; something like them sits behind every address you have ever opened.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →