How to Use Nginx with Django: Setup and Configuration Guide

To use nginx with Django, set up Gunicorn as the application server to run Django, then configure nginx as a reverse proxy to forward client requests to Gunicorn. This setup improves performance and security by letting nginx handle static files and manage connections.

Syntax

This is the basic nginx server block syntax to proxy requests to a Django app running with Gunicorn:

• server {}: Defines the server configuration.
• listen 80;: Listens on port 80 for HTTP requests.
• server_name: Your domain or IP address.
• location /: Proxies all requests to Gunicorn socket or port.
• proxy_pass: URL or socket where Gunicorn listens.
• location /static/: Serves static files directly from disk.

nginx

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://unix:/run/gunicorn.sock:;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /path/to/your/staticfiles/;
    }
}

Example

This example shows a complete minimal nginx config to serve a Django app with Gunicorn using a Unix socket and static files served by nginx.

nginx

server {
    listen 80;
    server_name mydjangoapp.com;

    location / {
        proxy_pass http://unix:/run/gunicorn.sock:;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /home/user/myproject/static/;
    }
}

Output

When nginx runs with this config and Gunicorn is running and listening on /run/gunicorn.sock, visiting http://mydjangoapp.com serves the Django app, and static files load from /home/user/myproject/static/.

Common Pitfalls

• Not running Gunicorn or misconfiguring its socket/port causes nginx to return 502 Bad Gateway.
• Incorrect alias path for static files leads to 404 errors.
• Missing proxy_set_header directives can break Django's request handling.
• Using root instead of alias in location /static/ causes wrong file paths.

nginx

location /static/ {
    root /home/user/myproject/static/;  # Wrong: serves /home/user/myproject/static/static/
}

# Correct:
location /static/ {
    alias /home/user/myproject/static/;
}

Quick Reference

Remember these tips when using nginx with Django:

• Use Gunicorn as the WSGI server behind nginx.
• Configure nginx to proxy requests to Gunicorn via socket or port.
• Serve static files directly with nginx using alias.
• Set proper headers in nginx to preserve client info.
• Check permissions on socket and static files for nginx access.

Key Takeaways

Use Gunicorn as the application server and nginx as a reverse proxy for Django.

Configure nginx to serve static files directly with the alias directive.

Always set proxy headers in nginx to forward client information correctly.

Ensure Gunicorn is running and accessible via the socket or port nginx proxies to.

Avoid using root instead of alias for static file locations to prevent path errors.