Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.opendir() method

Reference for fs.opendir() and the fs.Dir class in Node.js: stream directory entries one by one, async iteration, bufferSize, recursive and closing rules.

fs.opendir(path, options, callback) opens a directory and gives you an fs.Dir object. Instead of loading every name into one array like fs.readdir(), a Dir hands out entries a few at a time, so memory stays small even in folders with millions of files.

The easiest way to use it is for await (const entry of dir). Each entry is an fs.Dirent. When the loop ends, the directory handle is closed automatically.

NODE
import fs from "node:fs/promises";

for await (const entry of await fs.opendir(".")) {
  console.log(entry.name);
}

Try it

Node.js Async iteration over a directory

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 Manual reads, recursion and early exit

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
fs.opendir(path[, options], callback)   // callback(err, dir)
fs.opendirSync(path[, options]): fs.Dir
fsPromises.opendir(path[, options]): Promise<fs.Dir>

// options
{ encoding?: string, bufferSize?: number, recursive?: boolean }

// fs.Dir
dir.path                      // the path you opened
dir.read([callback])          // Promise<Dirent | null>
dir.readSync(): Dirent | null
dir.close([callback])         // Promise<undefined>
dir.closeSync()
dir[Symbol.asyncIterator]()
Name Description
options.encoding Encoding of entry names. Default "utf8".
options.bufferSize How many entries Node reads from the system per batch. Default 32. Higher values mean fewer system calls and more memory.
options.recursive Also yield entries of subdirectories. Default false.

Returns: a Dir. Its read() methods return the next Dirent, or null when no entries remain.

Errors: ENOENT and ENOTDIR when opening, ERR_DIR_CLOSED when you read or close a directory that is already closed, ERR_DIR_CONCURRENT_OPERATION if you start a second read or close while one is running.

Usage notes

  • Close what you open. Iterating to the end or leaving the loop with break or return closes it for you. If you call read() yourself, call close() in a finally block.
  • No order guarantee. Entries come in whatever order the file system returns them. . and .. are never yielded.
  • Do not mix styles. Do not call read() while a for await loop on the same Dir is running.
  • One pass only. A Dir cannot be rewound; open it again to start over.
  • Choose it for size, not for convenience. For small folders readdir is simpler and just as fast. opendir shines when you can stop early or process entries as they arrive.
  • Changes during iteration: entries added or removed while you are reading may or may not show up.
  • Recursive mode was added in Node 20.1 and does not follow symbolic links.