Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.stat() and lstat() methods

Reference for fs.stat(), fs.lstat() and fs.fstat() in Node.js: read size, type and times, follow or skip symlinks, throwIfNoEntry, bigint and common errors.

fs.stat(path, callback) asks the file system about a path and returns an fs.Stats object: size, type (file, directory, link, ...), permissions, owner and timestamps. It is the standard way to find out whether something exists and what it is.

fs.lstat() is identical except for symbolic links. stat follows the link and describes the target; lstat describes the link itself. fs.fstat() does the same for an already open file descriptor.

NODE
import fs from "node:fs";

const info = fs.statSync("package.json");
console.log(info.size, info.isFile());

Try it

Node.js Size, type and a missing path

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 stat versus lstat on a symlink

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.stat(path[, options], callback)      // callback(err, stats)
fs.statSync(path[, options]): Stats | BigIntStats | undefined
fsPromises.stat(path[, options]): Promise<Stats | BigIntStats>

fs.lstat / fs.lstatSync / fsPromises.lstat   // same signatures
fs.fstat(fd[, options], callback)            // also fs.fstatSync, filehandle.stat()

// options
{ bigint?: boolean, throwIfNoEntry?: boolean }
Name Description
path A string, Buffer or URL.
fd An open file descriptor (for fstat).
options.bigint Return numeric fields as bigint and add nanosecond fields. Default false.
options.throwIfNoEntry Sync forms only. If false, return undefined for a missing path instead of throwing. Default true.

Returns: a Stats (or BigIntStats) object.

Errors: ENOENT (missing path, or a broken link for stat), ENOTDIR (a parent component is a file), EACCES (no search permission on a parent directory), ELOOP (too many nested links).

Usage notes

  • Checking before using is racy. Another process can delete the file between your stat and your next call. Often it is safer to just try the operation and handle ENOENT.
  • throwIfNoEntry: false only suppresses "not found"; other errors such as EACCES still throw. It does not exist for the callback and promise versions, where you inspect err.code.
  • Use lstat when walking trees, so links are not followed into loops or out of the tree you meant to scan.
  • Read permission on the file is not needed, only search permission on the directories above it.
  • size is bytes, and for directories it is whatever the file system reports; do not add it up as the size of the contents. For free space see fs.statfs().
  • Large files: a regular number is exact up to 2^53, which is plenty for sizes, but ino values on some systems exceed it. Use { bigint: true } when comparing inode numbers.
  • Cheaper alternatives: fs.access() tests permissions, and readdir with withFileTypes avoids a stat per entry.