Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js UV_THREADPOOL_SIZE environment variable

Reference for UV_THREADPOOL_SIZE: how many threads libuv uses for fs, crypto, zlib and DNS work, the default of 4, the maximum, and when raising it helps.

Node.js runs your JavaScript on one thread, but some operations are blocking at the operating-system level or too CPU-heavy to run on the event loop: most fs calls, dns.lookup(), crypto.pbkdf2() and scrypt(), crypto.randomBytes() and zlib compression. libuv runs these on a pool of worker threads and delivers the result back to the loop as a callback or promise.

UV_THREADPOOL_SIZE sets how many threads that pool has. The default is 4. When more than that many pool tasks are queued, the extra ones wait, even though the event loop itself is idle.

NODE
// shell: UV_THREADPOOL_SIZE=16 node server.js

Try it

Node.js Pool size decides who runs first

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Network I/O does not use the pool

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// UV_THREADPOOL_SIZE=<integer 1..1024>
Part Description
Value Number of worker threads. Defaults to 4; libuv caps it at 1024.
Timing Read when the pool is first used. It must be in the environment before the process starts.

Edge cases: an invalid or empty value falls back to the default. Assigning process.env.UV_THREADPOOL_SIZE inside your program only works if it happens before anything has used the pool, which is not reliable in practice; set it from the outside.

Usage notes

  • What uses the pool: most asynchronous fs functions, dns.lookup() (not the dns.resolve*() family, which uses the network), crypto functions that take a callback such as pbkdf2, scrypt, randomBytes, randomFill and key generation, and zlib asynchronous compression.
  • What does not: TCP, UDP, HTTP and TLS sockets (the loop watches them with the kernel's event interface), timers, and worker_threads (those have their own threads).
  • Symptoms of an exhausted pool: file reads, DNS lookups or password hashes get slow together while CPU use of the main thread is low. A burst of bcrypt-style hashing can delay unrelated fs.readFile calls.
  • More threads help when tasks are mostly waiting (slow disks, network file systems, many DNS lookups). They do not help CPU-bound work beyond the number of CPU cores; extra threads only compete for the same cores.
  • Memory: every thread reserves a stack, so thousands of threads cost real memory. Typical values are 8 to 64.
  • Synchronous calls bypass the pool and block the loop instead, for example fs.readFileSync.
  • Alternatives: for heavy CPU jobs use worker threads; for hashing many passwords, queue them and limit concurrency in your code rather than relying on the pool as a limiter.
  • Observing it: the fs, dns and crypto pool sharing is why a stuck pool can look like "the whole server is slow" although HTTP handling itself is fine.