How to tune worker_connections in Nginx

Tuning worker_connections sets the per-worker concurrency ceiling in Nginx, which directly affects how many simultaneous client sockets can be served before requests queue or fail under peak load.

In Nginx, each worker_processes instance runs an event loop and can keep many connections open at once, with worker_connections defining the maximum per worker inside the events block. The rough upper bound is worker_processes * worker_connections, but real capacity depends on how connections are used (keepalives, long-lived upgrades, upstream proxying) and on operating system limits.

Increasing worker_connections without raising the open-file limit commonly triggers too many open files errors in /var/log/nginx/error.log, because each connection consumes file descriptors and proxying can consume additional ones. Syntax checks and reloads keep changes safe, while file descriptor limit changes on systemd hosts typically require a restart that can disrupt established connections.

1. Open the main Nginx configuration file.

   $ sudoedit /etc/nginx/nginx.conf

   On many Linux packages, /etc/nginx/nginx.conf includes additional files under /etc/nginx/conf.d and (on some distros) /etc/nginx/sites-enabled.

2. Identify the currently effective worker_processes and worker_connections values.

   $ sudo nginx -T 2>/dev/null | grep -E '^[[:space:]]*(worker_processes|worker_connections)[[:space:]]'
   worker_processes auto;
       worker_connections 1024;

   Theoretical cap ≈ worker_processes * worker_connections, but reverse proxying can consume more than one connection per client request.

3. Set worker_connections to the target value inside the events block.

   events {
       worker_connections 10240;
   }

   

   Keepalive clients, long-lived upgrades (for example WebSocket), and upstream proxy connections all count toward the limit.

4. Test the updated Nginx configuration for syntax errors.

   $ sudo nginx -t
   nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   nginx: configuration file /etc/nginx/nginx.conf test is successful

5. Reload Nginx to apply the configuration change.

   $ sudo systemctl reload nginx

6. Confirm the running configuration shows the updated worker_connections value.

   $ sudo nginx -T 2>/dev/null | grep -E '^[[:space:]]*worker_connections[[:space:]]'
       worker_connections 10240;

7. Check the open-file limit configured for the nginx service.

   $ sudo systemctl show -p LimitNOFILE nginx
   LimitNOFILE=1024

   Set LimitNOFILE comfortably above worker_connections to leave headroom for logs, upstream sockets, and other open files.

8. Create the systemd drop-in directory for the nginx unit.

   $ sudo install -d -m 0755 /etc/systemd/system/nginx.service.d

9. Create a drop-in that raises LimitNOFILE for the nginx unit.

   $ sudoedit /etc/systemd/system/nginx.service.d/limits.conf

   [Service]
   LimitNOFILE=65535

10. Reload systemd unit files after writing the drop-in.

    $ sudo systemctl daemon-reload

11. Restart Nginx to apply the updated LimitNOFILE.

    $ sudo systemctl restart nginx

    A restart can interrupt established connections, so apply during a low-traffic window when possible.

12. Confirm the Nginx service is active after the restart.

    $ sudo systemctl status nginx --no-pager
    ● nginx.service - A high performance web server and a reverse proxy server
         Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
         Active: active (running) since Mon 2025-12-08 09:41:12 UTC; 6s ago
    ##### snipped #####

13. Verify the new LimitNOFILE value reported for the nginx service.

    $ sudo systemctl show -p LimitNOFILE nginx
    LimitNOFILE=65535

14. Query the status endpoint during load to observe connection usage.

    $ curl -s http://127.0.0.1/nginx_status
    Active connections: 291
    server accepts handled requests
     101234 101234 203456
    Reading: 0 Writing: 12 Waiting: 279

    Related: How to enable Nginx stub_status page