Force File Downloads in NGINX with Content‑Disposition Headers

Sometimes you need to force users to download files from your website rather than view them in the browser. This is especially important when a site offers many downloadable resources, as forced downloads prevent streaming and can reduce server load.

Browser behavior

Modern browsers automatically open many file types (txt, pdf, jpg, etc.) inline.

Case 1: Simple attachment header

Adding the Content‑Disposition: attachment; header forces a download.

# Inline display (browser shows the file)
Content‑Disposition: inline; filename=foobar.pdf

# Forced download (e.g., Firefox)
Content‑Disposition: attachment; filename=foobar.pdf

NGINX configuration example:

location /download {
    add_header Content‑Disposition "attachment;";
}

Case 2: Preserve original filename and handle IE

For image, PDF, and other files, you may want the browser to prompt a save dialog using the original filename. IE can ignore the MIME type and still display the file, so the header must include a filename.

Solution: add Content‑Disposition: attachment; filename=yourfile in the response header.

location ~ ^/somepath/(.*)$ {
    add_header Content‑Disposition "attachment; filename=$1";
    alias "E:/apache-tomcat-7.0.32/webapps/upload/$1";
}

This uses a regular expression to capture the requested filename. Note that NGINX location priority is =, then ^~, and finally ~.

General rule for forced downloads

add_header Content‑Disposition "attachment; filename=$1";
default_type application/octet-stream;

Example for forcing all URLs under /downloads to download:

location /downloads {
    ...
    add_header Content‑Disposition "attachment; filename=$1";
    default_type application/octet-stream;
    ...
}

Example for forcing download of specific file extensions (jpg, png, mp3, etc.):

location ~* ^/.+\.(?:gif|jpe?g|png|mp4|mp3)$ {
    ...
    add_header Content‑Disposition "attachment; filename=$1";
    default_type application/octet-stream;
    ...
}

After making these changes, reload or restart NGINX:

nginx -s reload