NGINX Compression Configuration: Complete Setup Guide
NGINX is one of the most popular web servers, powering millions of websites. Configuring compression correctly can dramatically improve performance, reducing bandwidth usage by 60-80% and speeding up page loads. This guide covers everything you need to know about setting up gzip and Brotli compression in NGINX, from basic configuration to advanced optimization.
Basic Gzip Configuration
NGINX includes built-in gzip compression support. According to the NGINX gzip module documentation, enabling compression is straightforward:
http {
gzip on;
gzip_vary on;
gzip_min_length 1000;
gzip_comp_level 6;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}
Configuration Options Explained
Understanding each directive helps optimize compression:
- gzip on: Enables gzip compression
- gzip_vary on: Adds "Vary: Accept-Encoding" header for proper caching
- gzip_min_length: Only compress files larger than specified bytes (1000 = 1KB)
- gzip_comp_level: Compression level 1-9 (6 is balanced, 9 is maximum)
- gzip_types: MIME types to compress
The GZIP specification (RFC 1952) defines the compression format, while NGINX handles the HTTP headers as specified in MDN's Content-Encoding documentation.
Advanced Gzip Settings
For better performance, add these advanced options:
gzip_proxied any;
gzip_buffers 16 8k;
gzip_http_version 1.1;
gzip_disable "msie6";
- gzip_proxied: Compress responses for proxied requests (any = all requests)
- gzip_buffers: Sets buffer size (16 buffers of 8KB each)
- gzip_http_version: Minimum HTTP version (1.1 required for compression)
- gzip_disable: Disable compression for specific user agents (IE6 doesn't handle gzip well)
Brotli Compression Setup
Brotli offers 15-20% better compression than gzip. According to Wikipedia's Brotli article, it's becoming the preferred compression method. To use Brotli in NGINX, you need the ngx_brotli module:
# Install ngx_brotli module first
brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/json application/javascript text/xml application/xml;
brotli_min_length 1000;
Compression Level Optimization
Choosing the right compression level balances CPU usage and compression ratio. The DEFLATE algorithm (RFC 1951) supports levels 1-9:
- Level 1-3: Fast compression, ~60% ratio, low CPU usage - good for high-traffic sites
- Level 4-6: Balanced (recommended), ~70% ratio, moderate CPU - good default
- Level 7-9: Maximum compression, ~75% ratio, high CPU - use for static content
According to NGINX performance tuning guides, level 6 provides the best balance for most websites.
MIME Types to Compress
Only compress text-based content. According to web.dev's compression guide, compress these types:
- Text files: text/html, text/css, text/javascript, text/xml, text/plain
- Structured data: application/json, application/xml, application/javascript
- Web formats: application/rss+xml, application/atom+xml, application/manifest+json
- SVG: image/svg+xml (text-based vector graphics)
Don't compress:
- Images (JPEG, PNG, GIF, WebP) - already compressed
- Videos (MP4, WebM) - already compressed
- Fonts (WOFF, WOFF2) - already compressed
- Binary files - won't compress well
Caching Compressed Content
Proper caching is crucial for compression efficiency. The Vary header ensures browsers cache compressed and uncompressed versions separately:
gzip_vary on;
# Adds: Vary: Accept-Encoding
# Also set cache headers:
expires 1y;
add_header Cache-Control "public, immutable";
Testing Your Configuration
Verify compression is working:
- Check headers: Use curl to verify Content-Encoding header
- Compare sizes: Check compressed vs uncompressed file sizes
- Browser DevTools: Network tab shows compression status
- Online tools: Use compression checkers to verify
curl -H "Accept-Encoding: gzip" -I https://yoursite.com
# Look for: Content-Encoding: gzip
Tools like Lighthouse and WebPageTest can analyze your compression setup and provide optimization recommendations.
Performance Considerations
Compression uses CPU resources. Balance compression level with server capacity:
- High-traffic sites: Use lower compression levels (4-6) to reduce CPU load
- Static content: Pre-compress during build, use higher levels
- Dynamic content: Use moderate levels (6) for balance
- CPU-bound servers: Consider pre-compression or CDN compression
The GNU Gzip manual provides detailed information about compression level trade-offs and CPU usage.
Complete Configuration Example
http {
# Gzip compression
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_min_length 1000;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;
gzip_buffers 16 8k;
gzip_http_version 1.1;
gzip_disable "msie6";
# Brotli compression (if module installed)
brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/json application/javascript text/xml application/xml;
brotli_min_length 1000;
}
Troubleshooting
Common issues and solutions:
- Compression not working: Check gzip is enabled and MIME types are correct
- Files too small: Increase gzip_min_length if needed
- High CPU usage: Lower compression level or pre-compress static files
- Cache issues: Ensure gzip_vary is enabled
Conclusion
Properly configuring compression in NGINX can dramatically improve website performance, reducing bandwidth usage by 60-80% and speeding up page loads. Start with basic gzip configuration, optimize compression levels based on your server capacity, and consider Brotli for even better compression ratios. Regular testing and monitoring ensure your compression setup continues to deliver optimal performance.