Skip to main content

Include Directive

The include directive tells NGINX to read and insert configuration files from another location as if their contents were written directly at that place.

It is a core directive, not a module-specific feature.

Syntax

include path;
  • Ends with ;
  • path can be:
    • A single file
    • A wildcard (glob pattern)

Why include Exists​

NGINX configs can become large and hard to manage. include enables:

  • Modular configuration
  • Reusability
  • Cleaner main config
  • Easier maintenance
  • Environment-based setups

Where include Can Be Used (Contexts)​

The include directive is context-sensitive.

ContextAllowed
main✅
http✅
server✅
location✅
events✅

The included file must contain directives valid in the context where it is included

How include Works Internally​

When NGINX loads:

  1. It encounters include
  2. Reads the target file(s)
  3. Inserts the contents verbatim
  4. Validates directives normally

include is not dynamic — changes require reload.

Including a Single File​

Main Config (nginx.conf)

http {
    include /etc/nginx/mime.types;
}

Included File (`mime.types)

types {
    text/html html;
    image/jpeg jpg jpeg;
}
  • mime.types is inserted into the http block
  • Provides file extension → MIME mapping
  • This is the most common use of include

Using Wildcards (Glob Patterns)​

include /etc/nginx/conf.d/*.conf;
  • Includes all .conf files in the directory
  • Order is alphabetical
  • Non-matching files are ignored silently

Typical directory layout

/etc/nginx/
├── nginx.conf
├── conf.d/
│   ├── default.conf
│   ├── api.conf
│   └── ssl.conf

Modular Virtual Hosts​

nginx.conf

http {
    include /etc/nginx/conf.d/*.conf;
}

conf.d/example.conf

server {
    listen 80;
    server_name example.com;

    root /var/www/example;
}
  • Each file defines one virtual host
  • Easy to add/remove sites
  • No need to edit nginx.conf

Including Inside Server Context​

server {
    listen 443 ssl;
    server_name example.com;

    include /etc/nginx/snippets/ssl.conf;
}

snippets/ssl.conf

ssl_certificate /etc/ssl/certs/example.crt;
ssl_certificate_key /etc/ssl/private/example.key;
ssl_protocols TLSv1.2 TLSv1.3;
  • Keeps SSL config reusable
  • Avoids duplication across servers

Including Inside Location Context​

location /api/ {
    include /etc/nginx/snippets/proxy.conf;
}

proxy.conf

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://backend;

-Common proxy settings reused -Must contain only directives valid inside location

Include Order & Precedence​

NGINX processes includes in place and in order.

http {
    sendfile off;
    include tuning.conf;
}

If tuning.conf contains:

sendfile on;

Final value: sendfile on

Error Handling & Validation​

SituationResult
File not found❌ NGINX fails to start
No files match wildcard✅ No error
Invalid directive inside file❌ Config test fails
Wrong context❌ Startup error

Production Style Layout​

/etc/nginx/
├── nginx.conf
├── conf.d/
│   ├── default.conf
│   └── app.conf
├── snippets/
│   ├── ssl.conf
│   ├── proxy.conf
│   └── security.conf