Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js file system flags

Reference for Node.js file system flags such as r, r+, w, wx, a and ax: what each does to existing and missing files, with examples and common mistakes.

A file system flag is a short string that tells fs.open(), fs.readFile(), fs.writeFile(), fs.createWriteStream() and similar functions how to open a file: for reading, writing or appending, and what to do when the file does or does not already exist. They come from C's fopen modes, with extra letters for exclusive creation and synchronous writes.

Each string maps to a combination of the numeric O_* values in fs.constants. The string form is easier to read and works on every platform, so it is what you should normally use. The function-specific defaults are "r" for reads and "w" for whole-file writes.

NODE
import fs from "node:fs";

fs.writeFileSync("out.txt", "hello", { flag: "wx" }); // fail if out.txt exists

Try it

Node.js What each flag does to existing and missing files

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 Exclusive creation and appending in practice

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.open(path, flags, mode, callback)
fs.readFile(path, { flag: "r" }, callback)
fs.writeFile(path, data, { flag: "w", mode: 0o666 }, callback)
fs.createWriteStream(path, { flags: "w" })
Flag Opens for If the file exists If the file is missing
r reading opens at the start ENOENT
r+ reading and writing opens, content kept ENOENT
rs+ reading and writing, synchronous like r+ ENOENT
w writing emptied created
wx writing EEXIST created
w+ reading and writing emptied created
wx+ reading and writing EEXIST created
a appending content kept, writes go to the end created
ax appending EEXIST created
a+ reading and appending content kept created
ax+ reading and appending EEXIST created
as, as+ appending, synchronous like a, a+ created

The letter x means exclusive: creation fails if the path already exists. The letter s means synchronous: the operating system waits for the write to reach the device. The default file mode for new files is 0o666 (before the umask).

Errors: ENOENT (missing file with a flag that does not create), EEXIST (exclusive flag), EISDIR (opening a directory for writing), EACCES or EPERM (no permission), ERR_INVALID_ARG_VALUE for an unknown flag string.

Usage notes

  • w destroys content at once, before you write a single byte. If your program crashes between opening and writing, the old data is gone. Write a temporary file and rename() it for safe replacement.
  • wx is an atomic "create if absent". The check and the creation are one operation, so it is the right way to make lock files or avoid overwriting. A separate existsSync() followed by a write has a race.
  • Append ignores positions. On Linux, a file opened with a always writes at the end, even if you pass a position to write(). Use r+ when you need to patch the middle of a file.
  • r+ does not create. To open for update and create if missing, use a+ for appends or the numeric form O_RDWR | O_CREAT.
  • s flags are slow. rs+ and as bypass the cache for each write. For durability on a normal handle, call fsync() once at the end.
  • Streams call the option flags (plural); readFile and writeFile call it flag.
  • Numeric flags work too: fs.openSync(p, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW) reaches options the strings cannot express, such as refusing to follow a final symlink.
  • Windows: w on a hidden file can fail with EPERM. Directories cannot be opened for writing with any flag.