Node.js Reference ยท fs and fs/promises
Node.js fs.readdir() method
Reference for fs.readdir() in Node.js: list names, get Dirent objects with withFileTypes, walk trees with recursive, ordering, encodings and errors.
fs.readdir(path, options, callback) reads a directory and returns the names of the entries inside it. It does not include . and .., and it does not look inside subdirectories unless you ask it to with recursive: true.
With withFileTypes: true you get fs.Dirent objects instead of plain strings. They know whether each entry is a file, directory or link without an extra stat call per entry, which is much faster for large folders.
import fs from "node:fs"; const names = fs.readdirSync("."); const entries = fs.readdirSync(".", { withFileTypes: true });
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.readdir(path[, options], callback) // callback(err, entries) fs.readdirSync(path[, options]): string[] | Buffer[] | Dirent[] fsPromises.readdir(path[, options]): Promise<string[] | Buffer[] | Dirent[]> // options: an encoding string, or { encoding?: string, withFileTypes?: boolean, recursive?: boolean }
| Name | Description |
|---|---|
path |
A string, Buffer or URL naming a directory. |
options.encoding |
Encoding for the returned names. Default "utf8"; "buffer" returns Buffer objects. |
options.withFileTypes |
Return Dirent objects instead of strings. Default false. |
options.recursive |
Include entries from all subdirectories. Default false. |
Returns: an array. Without recursive, names are bare file names. With recursive, strings are paths relative to the directory you passed (such as a/b/two.txt), and the directories themselves are included.
Errors: ENOENT if the path does not exist, ENOTDIR if it is a file, EACCES without read permission.
Usage notes
- Order is not guaranteed. It depends on the file system and platform. Call
.sort()whenever order matters, including in tests. - Prefer
withFileTypeswhen you will test types. It avoids onestatper entry. On the few file systems that do not report types, Node falls back tolstatfor you. - Recursive output includes folders as well as files. Filter with
isFile()on Dirents, and useparentPathplusnameto build full paths. - Symbolic links are not followed in recursive mode, so loops cannot hang it. A link shows up as an entry of its own.
- Memory: every name lands in one array. For folders with hundreds of thousands of entries, iterate with
fs.opendir()instead. - Hidden files such as
.envare included. Node does no filtering. - Case and Unicode: names come back exactly as stored. macOS may return decomposed Unicode forms, so normalize before comparing.
- Recursive reading was added in Node 18.17 and 20.1. For pattern matching see
fs.glob().