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.
import fs from "node:fs/promises"; for await (const entry of await fs.opendir(".")) { console.log(entry.name); }
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.
Syntax
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
breakorreturncloses it for you. If you callread()yourself, callclose()in afinallyblock. - 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 afor awaitloop on the sameDiris running. - One pass only. A
Dircannot be rewound; open it again to start over. - Choose it for size, not for convenience. For small folders
readdiris simpler and just as fast.opendirshines 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.