Force file download with nginx

  1. Intro
  2. The code
  3. — What it does
  4. Related stuff


I have spend way too much time trying to figure out how to add a simple Content-Disposition response header for static files when the request URI contains a force_download GET parameter, except for hidden and PHP files. Sure I could pass the request to another (php) script, adjust the headers and back to nginx, but that doesn’t make sense as nginx already receives all required information and can do scripting. At last I built it and here it is for anyone’s sanity.

The idea is to use URLs with the special argument and it would download the file instead of viewing in the browser. The code below supports these combinations:

The code

— What it does

  • Extract the filename from the request path.
  • Build the correct string when the request URI contains the force_download element.
  • Extract custom filename from the force_download parameter.
  • Clear the string when a hidden file is requested. (security)
  • Reset the string when the header was already set by the backend, for example PHP.
  • Then set the Content-Disposition header only when the status code is 200 (ok). When $forceDownload is empty the header is removed from the response.

Add this to your virtual host to force file download with nginx and have fun!

Oh btw, you need the HttpHeadersMore 3rd party module. In Ubuntu just install the nginx-extras package with apt-get.

2015-01-11 – Replaced filename argument with inline regex
– changed order; backend headers rule
– cleaned up regexp
– added $filename at start to prevent error
– added filename argument

Leave a Reply

Your email address will not be published. Required fields are marked *