Force File Downloads in NGINX with Simple Header Configurations

Sometimes you need to force users to download files from your website rather than view them in the browser, especially when many downloadable resources are offered. This guide explains how to enforce file downloads using NGINX.

Situation 1: Basic Header

Adding the Content‑Disposition: attachment; header makes the browser download the file.

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

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

NGINX configuration example (place inside the appropriate server block):

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

Situation 2: Force Download for Specific Paths or Types

For image, PDF, or other files accessed via a certain path, you can force download and preserve the original filename using a regular‑expression location.

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

Note that NGINX location priority is =, then ^~, and finally ~.

General rule to force download for a URL:

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

Example for all URLs under /downloads:

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

Example for specific file extensions (e.g., .jpg, .png, .mp3):

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

After making changes, reload NGINX to apply them:

nginx -s reload