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 10240;

   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=1048576

   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=1048576

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 (/usr/lib/systemd/system/nginx.service; enabled; preset: enabled)
        Drop-In: /etc/systemd/system/nginx.service.d
                 └─limits.conf
         Active: active (running) since Mon 2025-12-29 22:08:39 UTC; 6s ago
           Docs: man:nginx(8)
        Process: 1607 ExecStartPre=/usr/sbin/nginx -t -q -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
        Process: 1608 ExecStart=/usr/sbin/nginx -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
       Main PID: 1610 (nginx)
          Tasks: 11 (limit: 9396)
         Memory: 45.7M (peak: 46.8M)
            CPU: 37ms
         CGroup: /system.slice/nginx.service
    ##### snipped #####

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

    $ sudo systemctl show -p LimitNOFILE nginx
    LimitNOFILE=1048576

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

    $ curl -s http://127.0.0.1/nginx_status
    Active connections: 1 
    server accepts handled requests
     1 1 1 
    Reading: 0 Writing: 1 Waiting: 0 

    Related: How to enable the Nginx stub_status page