Node.js Reference ยท Concepts and Pitfalls
The libuv thread pool in Node.js
What libuv's thread pool does in Node.js, which APIs use it (fs, crypto, zlib, dns.lookup), which do not, and how a saturated pool slows unrelated work.
Node.js is often described as single-threaded, which is true for your JavaScript but not for the process. Underneath, libuv keeps a small pool of worker threads and uses it for jobs that cannot be done without blocking: file system calls, some DNS work, and CPU-heavy native functions. Your code starts the job, the loop keeps running, and when a worker thread finishes, the result is queued as a callback on the main thread.
The pool has four threads by default and is shared by the whole process. That is plenty for most programs, but it is also a hidden shared resource: a few slow jobs can delay every other pool job, whatever module started it.
flowchart LR
JS["Your JavaScript<br/>(main thread)"] -->|"fs.readFile, pbkdf2, zlib"| Q["pool queue"]
Q --> W1["worker 1"]
Q --> W2["worker 2"]
Q --> W3["worker 3"]
Q --> W4["worker 4"]
W1 & W2 & W3 & W4 -->|"result"| L["event loop<br/>poll phase"]
L --> JS
N["sockets, timers"] -->|"kernel events, no pool"| LPool jobs go through a queue; network sockets are handled by the kernel's event mechanism and skip it.
Try it
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.
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.
What uses the pool
| Uses the pool | Does not use the pool |
|---|---|
Most fs functions (readFile, stat, writeFile, directory scans, fs.promises.*) |
TCP, UDP, HTTP, TLS and Unix socket I/O |
dns.lookup() and dns.lookupService() |
dns.resolve*() (uses c-ares and the network) |
crypto.pbkdf2, scrypt, randomBytes, randomFill, generateKeyPair, hkdf (callback or promise forms) |
Hashes of data you already have via createHash streams run on the main thread |
zlib asynchronous compression and decompression |
Timers, setImmediate, microtasks |
fs.cp, fs.readdir with recursive and other composite fs calls (many small pool jobs) |
worker_threads (own threads and loops) and child processes (own processes) |
Usage notes
- Default size 4, maximum 1024. Change it with
UV_THREADPOOL_SIZEbefore the process starts. - One shared queue. Slow
scryptcalls during logins can delayfs.readFilecalls that serve static files. If logins and disk reads both matter, limit concurrent hashing in your code. - A saturated pool looks like slow I/O, not like a busy CPU on the main thread: event-loop delay stays small while file reads and DNS lookups take longer and longer.
dns.lookup()is the surprise. It calls the system resolver in the pool, so many slow lookups can starve file access.dns.resolve4()and friends avoid the pool.- CPU-bound JavaScript never uses the pool. Moving a loop into
fsorcryptodoes nothing for it; use worker threads. - Sync variants bypass the queue and block the main thread for the duration; fine in startup code, harmful in request handlers.
- Threads are cheap but not free. Going from 4 to 64 threads helps waiting-bound workloads (network file systems, many lookups); CPU-bound hashing gains nothing beyond the number of cores.
- No per-job control. There is no priority, timeout or cancellation for a job already running in the pool; an
AbortSignalonly stops work that has not started.