Optimizing Nginx Worker Processes for Maximum Performance: A Practical Guide

Nginx can handle a lot of concurrent connections with a small process footprint, but only if its worker limits line up with the machine underneath it. The two settings people reach for first are worker_processes and worker_connections. They are useful, but they are also easy to over-tune. Setting both to huge numbers does not create free capacity. It can just move the bottleneck to file descriptors, memory, upstream servers, or the network stack.

The practical goal is to give Nginx enough workers to use the CPU cores it has, enough connection slots for real traffic, and enough operating system limits to avoid hitting the ceiling during normal bursts.

Understanding the Nginx Worker Architecture

Nginx operates using a master-worker model. The Master Process is responsible for reading and validating the configuration, binding to ports, and managing the worker processes. It performs non-critical tasks like monitoring system resources and restarting workers if necessary.

Worker Processes are where the heavy lifting occurs. These processes are single-threaded (in standard Nginx compilation) and use non-blocking system calls. Each worker handles thousands of concurrent connections efficiently using an event loop, allowing one process to manage multiple requests without blocking, which is key to Nginx’s performance.

Proper optimization involves balancing the number of workers (tying them to CPU resources) and setting the maximum number of connections each worker can handle.

Configuring worker_processes: The CPU Core Factor

The worker_processes directive determines how many worker processes Nginx should spawn. This setting directly affects how Nginx utilizes your server's CPU resources.

Best Practice: Matching Workers to Cores

The most common and highly recommended best practice is to set the number of worker processes equal to the number of CPU cores available on your server. This ensures that every core is utilized efficiently without incurring excessive overhead from context switching.

If the number of workers exceeds the number of cores, the operating system must frequently switch the CPU focus between competing Nginx processes (context switching), which introduces latency and reduces overall performance.

Using the auto Directive

For modern versions of Nginx (1.3.8 and later), the simplest and most effective configuration is using the auto parameter. Nginx will automatically detect the number of available CPU cores and set the worker processes accordingly.

# Recommended setting for most deployments
worker_processes auto;

Manual Configuration

If you need manual control or are using an older version, you can specify the exact number of workers. You can find the number of cores using system utilities:

# Find the number of CPU cores
grep processor /proc/cpuinfo | wc -l

If the system has 8 cores, the configuration would look like this:

# Manually setting worker processes to 8
worker_processes 8;

Tip: Matching the number of available cores is the safest starting point. In unusual I/O-heavy workloads you may test a different value, but benchmark it under realistic traffic before keeping it. For typical static serving, proxying, and TLS termination, auto is usually the least surprising choice.

Configuring worker_connections: The Concurrency Factor

The worker_connections directive is configured within the events block and defines the maximum number of simultaneous connections that a single worker process can handle. This includes connections to clients, connections to upstream proxy servers, and internal health check connections.

Calculating Maximum Clients

The theoretical maximum number of concurrent client connections your Nginx server can handle is calculated as follows:

$$\text{Max Clients} = \text{worker_processes} \times \text{worker_connections}$$

If you have 4 worker processes and 10,000 worker connections per process, Nginx could theoretically handle 40,000 simultaneous connections.

That number is only a rough upper bound. A proxied request may use one client connection and one upstream connection at the same time. WebSocket and long-polling traffic can hold slots for much longer than a normal page request. Keep-alive connections can also remain open while doing very little work. If Nginx is mostly serving static files, the math is closer to the simple formula. If it is acting as a reverse proxy, leave headroom.

Setting the Connection Limit

It is common to set worker_connections to a few thousand or more on busy servers, assuming memory and file descriptor limits can support it. Do not copy a large value blindly; pick a value that matches expected concurrency plus burst room.

# Example configuration for the events block

events {
    # Max concurrent connections per worker process
    worker_connections 16384;

    # Can help during bursts, but test fairness under load.
    multi_accept on;
}

System Limits (ulimit) Constraint

Crucially, the worker_connections setting is constrained by the operating system's limit on the number of open file descriptors (FDs) allowed per process, often controlled by the ulimit -n setting.

Nginx cannot open more connections than the OS allows file descriptors. Since every connection (client socket, log file, proxy socket) requires a file descriptor, it is vital that the system limit is set high enough.

Checking and Raising File Descriptor Limits

1. Check the current limit:

   ulimit -n
   

2. Temporarily increase the limit (for the current session):

   ulimit -n 65536
   

3. Permanently increase the limit (via /etc/security/limits.conf):

   Add the following lines, replacing nginx_user with the user Nginx runs as (often www-data or nginx):

   # /etc/security/limits.conf
   nginx_user soft nofile 65536
   nginx_user hard nofile 65536
   

Warning: Make sure the per-process file descriptor limit for the Nginx worker user is higher than worker_connections, with extra room for logs, upstream sockets, cache files, and other open files. System-wide limits matter too, but the per-process limit is the one that most often surprises people.

If Nginx is managed by systemd, /etc/security/limits.conf may not be enough. Many distributions start services with limits from the unit file. Check the active limit with:

cat /proc/$(pgrep -o nginx)/limits | grep "open files"

For a systemd override, use:

sudo systemctl edit nginx

Then add:

[Service]
LimitNOFILE=65536

Reload systemd and restart Nginx during a maintenance window:

sudo systemctl daemon-reload
sudo systemctl restart nginx

Advanced Tuning and Monitoring

Beyond the core directives, a few additional considerations can help fine-tune performance:

1. Pinning Worker Processes

In high-performance environments, especially on systems with multiple CPU sockets (NUMA architectures), you might want to use the worker_cpu_affinity directive. This tells the OS to restrict specific worker processes to specific CPUs, which can improve performance by ensuring that CPU caches remain hot and avoiding memory locality issues.

Example for an 8-core system:

worker_processes 8;
worker_cpu_affinity 00000001 00000010 00000100 00001000 00010000 00100000 01000000 10000000;

This setting is complex and usually only beneficial for extreme high-load situations; worker_processes auto is sufficient for most deployments.

2. Monitoring Performance Metrics

After applying optimizations, it is crucial to monitor the impact. Use the Nginx Stub Status module (or a tool like Prometheus/Grafana) to track key metrics:

Metric	Description	Optimization Check
Active Connections	Total connections currently handled.	Should be below the theoretical max.
Reading/Writing/Waiting	Connections in different states.	High Waiting counts often indicate long-lived HTTP Keep-Alives (good) or insufficient processing resources (bad).
Request Rate	Requests per second.	Used to measure the actual performance improvement after configuration changes.

If you observe high CPU utilization across all cores and high request rates, your worker_processes are likely configured correctly. If you have idle CPU cores during peak traffic, consider reviewing your configuration or checking for blocking I/O operations outside of Nginx.

3. Connection Overflow Strategy

If the server hits the maximum connection limit (worker_processes * worker_connections), new connections may fail or sit in queues until they time out. Increasing worker_connections can help only when Nginx is the actual bottleneck. If upstream application servers are saturated, raising the limit can make the outage feel worse because more requests pile up behind slow backends.

Use the error log as a signal. Messages like worker_connections are not enough point directly at Nginx limits. A rise in upstream timed out, connect() failed, or 502/504 responses points more toward backend capacity, network issues, or timeout settings.

A Reasonable Starting Configuration

For a small or medium reverse proxy, this is a sane baseline:

worker_processes auto;
worker_rlimit_nofile 65536;

events {
    worker_connections 8192;
    multi_accept off;
}

Why multi_accept off here? It is the conservative default on many systems. Turning it on can help a worker drain a pending accept queue quickly, but under some traffic patterns it may let one worker grab a large batch while others sit idle. If you have bursty traffic and a tested reason to enable it, do so. If you are tuning a general-purpose web server, keep the baseline simple and measure first.

If the server handles many WebSocket connections, Server-Sent Events, or long-lived API streams, raise the connection limit more aggressively and pay close attention to memory. A server with 20,000 mostly idle WebSocket clients has a different profile from a server doing 20,000 short static file requests.

How to Validate the Change

Before changing production, capture a small baseline:

nginx -T | grep -E 'worker_processes|worker_connections|worker_rlimit_nofile'
ss -s
ulimit -n

After the change, check that Nginx actually loaded it:

sudo nginx -t
sudo systemctl reload nginx
ps -o pid,comm,nlwp,pcpu,pmem -C nginx
cat /proc/$(pgrep -n nginx)/limits | grep "open files"

Then watch behavior during real traffic. If all CPU cores are busy and latency rises, Nginx may be doing useful work and reaching CPU capacity. If CPU is low but connections queue or time out, look at file descriptors, upstream saturation, DNS resolution, disk I/O, or firewall limits. Worker tuning is one lever, not the whole performance story.

Reading the Numbers in Context

A common mistake is treating "active connections" as the same thing as "active users." It is not. One browser can open several connections for assets. One API client may keep a connection alive between requests. One WebSocket client may hold a connection for hours while sending almost no traffic. When you size worker_connections, think in terms of concurrent sockets, not people.

For a reverse proxy, also remember the upstream side. If 4,000 clients are waiting on proxied responses, Nginx may also be holding thousands of upstream sockets. That is why a server can run out of file descriptors before the simple client-side calculation says it should. This is especially visible when the upstream application slows down: requests stay open longer, concurrency rises, and Nginx starts consuming more sockets even though the incoming request rate has not changed.

Keep-alive settings influence this too. Long keep-alive timeouts reduce connection churn, which can help busy sites, but they also keep idle sockets around longer. Very short keep-alive timeouts free sockets faster but can increase TLS handshakes and connection setup overhead. There is no perfect value; use traffic shape as the guide. A public website with many short visits may need a different balance from an internal API with a small number of persistent clients.

If you are tuning inside a container, verify the limits inside the container and at the host or orchestrator level. A Kubernetes pod, Docker container, or systemd service may have a lower nofile limit than the host shell you used to test. Always check the running Nginx process, not just your login session.

Summary of Best Practices

Directive	Recommended Value	Rationale
worker_processes	auto (or core count)	Ensures optimal CPU utilization and minimizes context switching overhead.
worker_connections	Start with a few thousand; raise based on measured concurrency	Provides connection headroom without hiding other bottlenecks.
OS Limit (ulimit -n)	Higher than per-worker connection needs, with extra room	Provides file descriptors for client sockets, upstream sockets, logs, and cache files.
multi_accept	Test before enabling	Can help with bursts, but is not automatically better for every workload.

The best Nginx worker configuration is usually plain: worker_processes auto, a connection limit that reflects real concurrency, and file descriptor limits that are high enough for the workload. Tune it, verify the active process limits, and keep watching the error log. If the symptoms point upstream, fix the upstream instead of making Nginx accept more work than the application can finish.