Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.statfs() method

Reference for fs.statfs() in Node.js: read block size, total and free space and inode counts for the file system holding a path, with bigint and error notes.

fs.statfs(path, callback) reports facts about the whole file system (the mounted volume) that contains a path, not about the file itself. You get the block size, how many blocks exist and how many are free, and how many inodes (file slots) exist and are free. Multiply blocks by block size and you have the size of the volume.

Use it for "is there enough room before I write this 2 GB file?" checks, disk-usage meters and health endpoints. For information about one file, use fs.stat().

NODE
import fs from "node:fs";

const info = fs.statfsSync("/");
const freeBytes = info.bavail * info.bsize;
console.log(`${(freeBytes / 1e9).toFixed(1)} GB available`);

Try it

Node.js Reading the fields

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 Bigint values and a free-space check

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.statfs(path[, options], callback)
fs.statfsSync(path[, options]): fs.StatFs
fsPromises.statfs(path[, options]): Promise<fs.StatFs>
Name Description
path Any path on the volume you are asking about. A string, Buffer or URL.
options.bigint If true, numeric fields are bigint instead of number. Default false.
callback Called as callback(err, stats).

The returned StatFs object has these fields:

Field Meaning
type File system type code (a magic number such as 0xEF53 for ext4).
bsize Optimal transfer block size in bytes.
frsize Fundamental block size: the unit blocks, bfree and bavail are counted in on Linux. Present in Node.js 24.
blocks Total data blocks.
bfree Free blocks, including those reserved for the superuser.
bavail Free blocks an unprivileged process can use.
files Total file nodes (inodes).
ffree Free file nodes.

Errors: ENOENT if the path does not exist, EACCES if a directory on the way cannot be searched.

Usage notes

  • Use bavail, not bfree, to answer "how much can my program write?". Many Linux file systems reserve a slice for root, so bfree can be larger.
  • Block counts use the fragment size. On Linux the counts are in units of frsize, which usually equals bsize but can differ. When frsize is present, prefer it for byte totals.
  • Numbers can be huge. Large volumes fit in a number today, but use { bigint: true } when you multiply to bytes on petabyte-scale or network storage.
  • It is a snapshot. Other processes may fill the disk a millisecond later, so a pre-check does not replace handling ENOSPC on write.
  • File system specific. Network, overlay and virtual file systems may report zeros or unrelated values for inode counts. Containers often show the host's volume.
  • The type code is platform defined, so do not compare it unless you target one operating system.
  • Added in Node.js 19.6 / 18.15. Older versions need a child process running df.