Node.js Reference ยท fs and fs/promises
Node.js fsPromises.open() method
Reference for fsPromises.open() in Node.js: open a file and get a FileHandle, flags and mode, closing with finally or await using, and common error codes.
fsPromises.open(path[, flags[, mode]]) opens a file and returns a promise for a FileHandle. The handle stays open until you close it, so you can make several reads, writes and metadata calls on the same file without reopening it. This is the entry point for anything beyond "read it all" or "write it all": reading a header, patching bytes in the middle, tailing a file, or writing records at known positions.
The second argument is a file system flag such as "r" (the default), "w", "a+" or "wx".
import { open } from "node:fs/promises"; const handle = await open("data.bin", "r"); try { const head = Buffer.alloc(4); await handle.read(head, 0, 4, 0); console.log(head); } finally { await handle.close(); }
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
fsPromises.open(path[, flags[, mode]]): Promise<FileHandle>
| Name | Description |
|---|---|
path |
A string, Buffer or URL. |
flags |
A string flag or a number built from fs.constants.O_*. Default "r". |
mode |
Permissions for a newly created file, as a number or an octal string. Default 0o666, reduced by the umask. |
Returns: a promise for a FileHandle.
Errors: ENOENT (missing file or parent), EEXIST (exclusive flag on an existing file), EISDIR (directory opened for writing), EACCES/EPERM, EMFILE (too many open files), and ERR_INVALID_ARG_VALUE for an unknown flag string.
Usage notes
- Always close. Use
try/finally, orawait usingwhere available (Node.js 24 supports it). An unclosed handle leaks a descriptor, and when the object is garbage collected Node prints a warning and closes it for you. - Open once, use many times. Reopening the same file for every small read is slow. Keep the handle for as long as you need the file.
EMFILEappears when a process has too many open files, usually from opening thousands in parallel. Limit concurrency, for example with a small pool of workers.- Directories can be opened with
"r"on Linux and macOS (useful forsync()on a directory), but you cannot read data from them. - Flag choice matters:
"w"truncates immediately,"r+"does not create,"a"always writes at the end. See File system flags for the full table. - The legacy API is different:
fs.open()returns a numeric descriptor, not an object. Do not mix descriptors and handles: closing a handle closes its descriptor. - Shortcuts exist for whole files.
fsPromises.readFile()andfsPromises.writeFile()open and close the file for you. - Streams from a handle:
handle.createReadStream()andhandle.createWriteStream()close the handle when they finish unless you setautoClose: false.