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().
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
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.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, notbfree, to answer "how much can my program write?". Many Linux file systems reserve a slice for root, sobfreecan be larger. - Block counts use the fragment size. On Linux the counts are in units of
frsize, which usually equalsbsizebut can differ. Whenfrsizeis present, prefer it for byte totals. - Numbers can be huge. Large volumes fit in a
numbertoday, 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
ENOSPCon 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
typecode 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.