Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import fs from "node:fs";

const names = fs.readdirSync(".");
const entries = fs.readdirSync(".", { withFileTypes: true });

Try it

Node.js Names, entry types and sorting

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 Recursive listing and errors

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.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 withFileTypes when you will test types. It avoids one stat per entry. On the few file systems that do not report types, Node falls back to lstat for you.
  • Recursive output includes folders as well as files. Filter with isFile() on Dirents, and use parentPath plus name to 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 .env are 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().