Enabling the Nginx Directory Index Listing

If you're using Nginx as a web server and want to display an Nginx directory index listing when navigating to a particular directory, then you have a couple of options. One way to achieve this is through the use of an index file (index.html). However, another method that can be used is through enabling the ngx_http_autoindex_module.

This post will go through how to enable the Nginx directory index listing using both of these methods as well as outline the directives available in the autoindex module.

Explaining the Nginx directory index file

By default, Nginx tries to display a directory listing when a particular URL path ends with a /. For example, if you were to use the path /assets/css/, then Nginx would look in the /css/ directory to see if it can find an index.html file (that is if it has permissions). If the autoindex module is not active and there is no index.html present, then Nginx will return a 404 Not Found error.

However, in the event that you do have an index.html file in that directory, then Nginx will use that to generate a directory listing of the assets that live within that directory. For example, as seen in the screenshot below, an index is generated within the /test/ directory which then displays both items that live within /test/.

How to enable automatic Nginx directory index listings

As previously mentioned, if you don't have an index.html file in a particular directory that you want to generate a listing for, then navigating to that URL path will return a 404 Not Found error. However, the Nginx autoindex module provides an easy way for a particular directory to automatically generate a listing. Adding autoindex to your Nginx configuration is quite easy. Simply add it to your Nginx location directive as so:

location /somedirectory/ {
    autoindex on;
}

Once that change is made, restart your Ngin x server sudo service nginx restart. Now, instead of returning a 404 error, the web server will return an Nginx directory index listing similar to what is shown in the previous section for the directory/directories you have defined in your location block.

Nginx autoindex directives

Besides simply using autoindex on or off, there are also three other directives you can configure with this module. These include the following:

• autoindex_exact_size; - This directive specifies whether Nginx should display the exact file sizes of the output in the directory index or simply round to the nearest KB, MB, or GB. This directive has two options: on or off.
• autoindex_format; - This directive specifies what format the Nginx index listing should be outputted to. This directive has four options: html, xml, json, or jsonp.
• autoindex_localtime; - This directive specifies whether the times for the directory listing should be outputted to local time or UTC. This directive has two options: on or off.

An example of a location directive using all four autoindex options could resemble the following.

location /somedirectory/ {
    autoindex on;
    autoindex_exact_size off;
    autoindex_format html;
    autoindex_localtime on;
}

Summary

The ngx_http_autoindex_module provides users with an easy to use method that allows them to display a directory listing whether there is an index.html present or not. This can be quite useful if you want to show the Nginx directory index listing for many directories but don't want to go through the process of creating an index file for each one. Additionally, this method also helps reduce the risk of any 404 errors in the event you forget to include an index file for a particular directory.