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.
import fs from "node:fs"; fs.writeFileSync("out.txt", "hello", { flag: "wx" }); // fail if out.txt exists
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.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
wdestroys 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 andrename()it for safe replacement.wxis 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 separateexistsSync()followed by a write has a race.- Append ignores positions. On Linux, a file opened with
aalways writes at the end, even if you pass a position towrite(). User+when you need to patch the middle of a file. r+does not create. To open for update and create if missing, usea+for appends or the numeric formO_RDWR | O_CREAT.sflags are slow.rs+andasbypass the cache for each write. For durability on a normal handle, callfsync()once at the end.- Streams call the option
flags(plural);readFileandwriteFilecall itflag. - 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:
won a hidden file can fail withEPERM. Directories cannot be opened for writing with any flag.