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.
import fs from "node:fs"; const info = fs.statSync("package.json"); console.log(info.size, info.isFile());
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.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
statand your next call. Often it is safer to just try the operation and handleENOENT. throwIfNoEntry: falseonly suppresses "not found"; other errors such asEACCESstill throw. It does not exist for the callback and promise versions, where you inspecterr.code.- Use
lstatwhen 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.
sizeis 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 seefs.statfs().- Large files: a regular
numberis exact up to 2^53, which is plenty for sizes, butinovalues on some systems exceed it. Use{ bigint: true }when comparing inode numbers. - Cheaper alternatives:
fs.access()tests permissions, andreaddirwithwithFileTypesavoids astatper entry.