Skip to content
Tutorials Center
My learning

Topics

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"| L

Pool jobs go through a queue; network sockets are handled by the kernel's event mechanism and skip it.

Try it

Node.js Who waits for 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.

Node.js Sync calls block the loop, async calls do not

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_SIZE before the process starts.
  • One shared queue. Slow scrypt calls during logins can delay fs.readFile calls 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 fs or crypto does 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 AbortSignal only stops work that has not started.