Skip to main content
fs - Node documentation

Usage in Deno

import * as mod from "node:fs";

The node:fs module enables interacting with the file system in a way modeled on standard POSIX functions.

To use the promise-based APIs:

import * as fs from 'node:fs/promises';

To use the callback and sync APIs:

import * as fs from 'node:fs';

All file system operations have synchronous, callback, and promise-based forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).

Classes

c
Dir

A class representing a directory stream.

c
Dirent

A representation of a directory entry, which can be a file or a subdirectorywithin the directory, as returned by reading from an fs.Dir. Thedirectory entry is a combination of the file name and file type pairs.

c
ReadStream

Instances of fs.ReadStream are created and returned using the createReadStream function.

c
WriteStream

Instances of fs.WriteStream are created and returned using the createWriteStream function.

Functions

f
access

Tests a user's permissions for the file or directory specified by path.The mode argument is an optional integer that specifies the accessibilitychecks to be performed. mode should be either the value fs.constants.F_OK or a mask consisting of the bitwise OR of any of fs.constants.R_OK, fs.constants.W_OK, and fs.constants.X_OK(e.g.fs.constants.W_OK | fs.constants.R_OK). Check File access constants forpossible values of mode.

f
accessSync

Synchronously tests a user's permissions for the file or directory specifiedby path. The mode argument is an optional integer that specifies theaccessibility checks to be performed. mode should be either the value fs.constants.F_OK or a mask consisting of the bitwise OR of any of fs.constants.R_OK, fs.constants.W_OK, andfs.constants.X_OK (e.g.fs.constants.W_OK | fs.constants.R_OK). Check File access constants forpossible values of mode.

f
appendFile

Asynchronously append data to a file, creating the file if it does not yetexist. data can be a string or a Buffer.

f
appendFileSync

Synchronously append data to a file, creating the file if it does not yetexist. data can be a string or a Buffer.

f
chmod

Asynchronously changes the permissions of a file. No arguments other than apossible exception are given to the completion callback.

f
chmodSync

For detailed information, see the documentation of the asynchronous version ofthis API: chmod.

f
chown

Asynchronously changes owner and group of a file. No arguments other than apossible exception are given to the completion callback.

f
chownSync

Synchronously changes owner and group of a file. Returns undefined.This is the synchronous version of chown.

f
close

Closes the file descriptor. No arguments other than a possible exception aregiven to the completion callback.

f
closeSync

Closes the file descriptor. Returns undefined.

f
copyFile

Asynchronously copies src to dest. By default, dest is overwritten if italready exists. No arguments other than a possible exception are given to thecallback function. Node.js makes no guarantees about the atomicity of the copyoperation. If an error occurs after the destination file has been opened forwriting, Node.js will attempt to remove the destination.

f
copyFileSync

Synchronously copies src to dest. By default, dest is overwritten if italready exists. Returns undefined. Node.js makes no guarantees about theatomicity of the copy operation. If an error occurs after the destination filehas been opened for writing, Node.js will attempt to remove the destination.

f
cp

Asynchronously copies the entire directory structure from src to dest,including subdirectories and files.

f
cpSync

Synchronously copies the entire directory structure from src to dest,including subdirectories and files.

f
createReadStream

Unlike the 16 KiB default highWaterMark for a stream.Readable, the streamreturned by this method has a default highWaterMark of 64 KiB.

f
createWriteStream

options may also include a start option to allow writing data at someposition past the beginning of the file, allowed values are in the[0, Number.MAX_SAFE_INTEGER] range. Modifying a file rather thanreplacing it may require the flags option to be set to r+ rather than thedefault w. The encoding can be any one of those accepted by Buffer.

f
existsSync

Returns true if the path exists, false otherwise.

f
fchmod

Sets the permissions on the file. No arguments other than a possible exceptionare given to the completion callback.

f
fchmodSync

Sets the permissions on the file. Returns undefined.

f
fchown

Sets the owner of the file. No arguments other than a possible exception aregiven to the completion callback.

f
fchownSync

Sets the owner of the file. Returns undefined.

f
fdatasync

Forces all currently queued I/O operations associated with the file to theoperating system's synchronized I/O completion state. Refer to the POSIX fdatasync(2) documentation for details. No arguments otherthan a possibleexception are given to the completion callback.

f
fdatasyncSync

Forces all currently queued I/O operations associated with the file to theoperating system's synchronized I/O completion state. Refer to the POSIX fdatasync(2) documentation for details. Returns undefined.

f
fstat

Invokes the callback with the fs.Stats for the file descriptor.

f
fstatSync

Retrieves the fs.Stats for the file descriptor.

f
fsync

Request that all data for the open file descriptor is flushed to the storagedevice. The specific implementation is operating system and device specific.Refer to the POSIX fsync(2) documentation for more detail. No arguments otherthan a possible exception are given to the completion callback.

f
fsyncSync

Request that all data for the open file descriptor is flushed to the storagedevice. The specific implementation is operating system and device specific.Refer to the POSIX fsync(2) documentation for more detail. Returns undefined.

f
ftruncate

Truncates the file descriptor. No arguments other than a possible exception aregiven to the completion callback.

f
ftruncateSync

Truncates the file descriptor. Returns undefined.

f
futimes

Change the file system timestamps of the object referenced by the supplied filedescriptor. See utimes.

f
futimesSync

Synchronous version of futimes. Returns undefined.

f
glob

Retrieves the files matching the specified pattern.

f
globSync

Retrieves the files matching the specified pattern.

f
lchown

Set the owner of the symbolic link. No arguments other than a possibleexception are given to the completion callback.

f
lchownSync

Set the owner for the path. Returns undefined.

f
linkSync

Creates a new link from the existingPath to the newPath. See the POSIX link(2) documentation for more detail. Returns undefined.

f
lstat

Retrieves the fs.Stats for the symbolic link referred to by the path.The callback gets two arguments (err, stats) where stats is a fs.Stats object. lstat() is identical to stat(), except that if path is a symboliclink, then the link itself is stat-ed, not the file that it refers to.

f
lutimes

Changes the access and modification times of a file in the same way as utimes, with the difference that if the path refers to a symboliclink, then the link is not dereferenced: instead, the timestamps of thesymbolic link itself are changed.

f
lutimesSync

Change the file system timestamps of the symbolic link referenced by path.Returns undefined, or throws an exception when parameters are incorrect orthe operation fails. This is the synchronous version of lutimes.

f
mkdir

Asynchronously creates a directory.

f
mkdirSync

Synchronously creates a directory. Returns undefined, or if recursive is true, the first directory path created.This is the synchronous version of mkdir.

f
mkdtemp

Creates a unique temporary directory.

f
mkdtempSync

Returns the created directory path.

f
open

Asynchronous file open. See the POSIX open(2) documentation for more details.

f
openAsBlob

Returns a Blob whose data is backed by the given file.

f
opendir

Asynchronously open a directory. See the POSIX opendir(3) documentation formore details.

f
opendirSync

Synchronously open a directory. See opendir(3).

f
openSync

Returns an integer representing the file descriptor.

f
promises.access

Tests a user's permissions for the file or directory specified by path.The mode argument is an optional integer that specifies the accessibilitychecks to be performed. mode should be either the value fs.constants.F_OK or a mask consisting of the bitwise OR of any of fs.constants.R_OK, fs.constants.W_OK, and fs.constants.X_OK(e.g.fs.constants.W_OK | fs.constants.R_OK). Check File access constants forpossible values of mode.

f
promises.appendFile

Asynchronously append data to a file, creating the file if it does not yetexist. data can be a string or a Buffer.

f
promises.chmod

Changes the permissions of a file.

f
promises.chown

Changes the ownership of a file.

f
promises.copyFile

Asynchronously copies src to dest. By default, dest is overwritten if italready exists.

f
promises.cp

Asynchronously copies the entire directory structure from src to dest,including subdirectories and files.

f
promises.glob

Retrieves the files matching the specified pattern.

f
promises.lchown

Changes the ownership on a symbolic link.

f
promises.lstat

Equivalent to fsPromises.stat() unless path refers to a symbolic link,in which case the link itself is stat-ed, not the file that it refers to.Refer to the POSIX lstat(2) document for more detail.

f
promises.lutimes

Changes the access and modification times of a file in the same way as fsPromises.utimes(), with the difference that if the path refers to asymbolic link, then the link is not dereferenced: instead, the timestamps ofthe symbolic link itself are changed.

f
promises.mkdir

Asynchronously creates a directory.

f
promises.mkdtemp

Creates a unique temporary directory. A unique directory name is generated byappending six random characters to the end of the provided prefix. Due toplatform inconsistencies, avoid trailing X characters in prefix. Someplatforms, notably the BSDs, can return more than six random characters, andreplace trailing X characters in prefix with random characters.

f
promises.open

Opens a FileHandle.

f
promises.opendir

Asynchronously open a directory for iterative scanning. See the POSIX opendir(3) documentation for more detail.

f
promises.readdir

Reads the contents of a directory.

f
promises.readFile

Asynchronously reads the entire contents of a file.

f
promises.realpath

Determines the actual location of path using the same semantics as the fs.realpath.native() function.

f
promises.rename

Renames oldPath to newPath.

f
promises.rm

Removes files and directories (modeled on the standard POSIX rm utility).

f
promises.rmdir

Removes the directory identified by path.

f
promises.stat
No documentation available
f
promises.statfs
No documentation available
f
promises.truncate

Truncates (shortens or extends the length) of the content at path to len bytes.

f
promises.utimes

Change the file system timestamps of the object referenced by path.

f
promises.watch

Returns an async iterator that watches for changes on filename, where filenameis either a file or a directory.

f
promises.writeFile

Asynchronously writes data to a file, replacing the file if it already exists. data can be a string, a buffer, anAsyncIterable, or anIterable object.

f
read

Read data from the file specified by fd.

f
readdir

Reads the contents of a directory. The callback gets two arguments (err, files) where files is an array of the names of the files in the directory excluding '.' and '..'.

f
readdirSync

Reads the contents of the directory.

f
readFile

Asynchronously reads the entire contents of a file.

f
readFileSync

Returns the contents of the path.

f
readlinkSync

Returns the symbolic link's string value.

f
readSync

Returns the number of bytesRead.

f
readv

Read from a file specified by fd and write to an array of ArrayBufferViewsusing readv().

f
readvSync

For detailed information, see the documentation of the asynchronous version ofthis API: readv.

f
N
realpath

Asynchronously computes the canonical pathname by resolving ., .., andsymbolic links.

f
f
N
realpathSync

Returns the resolved pathname.

f
realpathSync.native
No documentation available
f
rename

Asynchronously rename file at oldPath to the pathname providedas newPath. In the case that newPath already exists, it willbe overwritten. If there is a directory at newPath, an error willbe raised instead. No arguments other than a possible exception aregiven to the completion callback.

f
renameSync

Renames the file from oldPath to newPath. Returns undefined.

f
rm

Asynchronously removes files and directories (modeled on the standard POSIX rm utility). No arguments other than a possible exception are given to thecompletion callback.

f
rmdir

Asynchronous rmdir(2). No arguments other than a possible exception are givento the completion callback.

f
rmdirSync

Synchronous rmdir(2). Returns undefined.

f
rmSync

Synchronously removes files and directories (modeled on the standard POSIX rm utility). Returns undefined.

f
stat

Asynchronous stat(2). The callback gets two arguments (err, stats) wherestats is an fs.Stats object.

f
statfs

Asynchronous statfs(2). Returns information about the mounted file system whichcontains path. The callback gets two arguments (err, stats) where statsis an fs.StatFs object.

f
statfsSync

Synchronous statfs(2). Returns information about the mounted file system whichcontains path.

f
symlinkSync

Returns undefined.

f
truncate

Truncates the file. No arguments other than a possible exception aregiven to the completion callback. A file descriptor can also be passed as thefirst argument. In this case, fs.ftruncate() is called.

f
truncateSync

Truncates the file. Returns undefined. A file descriptor can also bepassed as the first argument. In this case, fs.ftruncateSync() is called.

f
unlinkSync

Synchronous unlink(2). Returns undefined.

f
unwatchFile

Stop watching for changes on filename. If listener is specified, only thatparticular listener is removed. Otherwise, all listeners are removed,effectively stopping watching of filename.

f
utimes

Change the file system timestamps of the object referenced by path.

f
utimesSync

Returns undefined.

f
watch

Watch for changes on filename, where filename is either a file or adirectory.

f
watchFile

Watch for changes on filename. The callback listener will be called eachtime the file is accessed.

f
write

Write buffer to the file specified by fd.

f
writeFile

When file is a filename, asynchronously writes data to the file, replacing thefile if it already exists. data can be a string or a buffer.

f
writeFileSync

Returns undefined.

f
writeSync

For detailed information, see the documentation of the asynchronous version ofthis API: write.

f
writev

Write an array of ArrayBufferViews to the file specified by fd using writev().

f
writevSync

For detailed information, see the documentation of the asynchronous version ofthis API: writev.

f
exists

Test whether or not the given path exists by checking with the file system.Then call the callback argument with either true or false:

f
lchmod

Changes the permissions on a symbolic link. No arguments other than a possibleexception are given to the completion callback.

f
lchmodSync

Changes the permissions on a symbolic link. Returns undefined.

f
promises.lchmod

Changes the permissions on a symbolic link.

Interfaces

I
BigIntOptions
No documentation available
I
I
BigIntStatsFs
No documentation available
I
CopyOptions
No documentation available
I
CopySyncOptions
No documentation available
I
CreateReadStreamFSImplementation
No documentation available
I
I
FSImplementation
No documentation available
I
GlobOptions
No documentation available
I
GlobOptionsWithFileTypes
No documentation available
I
GlobOptionsWithoutFileTypes
No documentation available
I
MakeDirectoryOptions
No documentation available
I
ObjectEncodingOptions
No documentation available
I
OpenAsBlobOptions
No documentation available
I
OpenDirOptions
No documentation available
I
promises.FileChangeInfo
No documentation available
I
promises.FileReadResult
No documentation available
I
promises.FlagAndOpenMode
No documentation available
I
promises.ReadableWebStreamOptions
No documentation available
I
ReadAsyncOptions
No documentation available
I
ReadStreamOptions
No documentation available
I
ReadSyncOptions
No documentation available
I
ReadVResult
No documentation available
I
RmDirOptions
No documentation available
I
I
StatFsOptions
No documentation available
I
StatOptions
No documentation available
c
I
Stats

A fs.Stats object provides information about a file.

c
I
StatsFs

Provides information about a mounted file system.

I
StatSyncFn
No documentation available
I
StatSyncOptions
No documentation available
I
StatWatcher

Class: fs.StatWatcher

I
WatchFileOptions

Watch for changes on filename. The callback listener will be called eachtime the file is accessed.

I
WatchOptions
No documentation available
I
WriteStreamOptions
No documentation available
I
WriteVResult
No documentation available

Namespaces

N
constants
No documentation available
N
promises

The fs/promises API provides asynchronous file system methods that returnpromises.

Type Aliases

T
BigIntStatsListener
No documentation available
T
BufferEncodingOption
No documentation available
T
EncodingOption
No documentation available
T
Mode
No documentation available
T
NoParamCallback
No documentation available
T
OpenMode
No documentation available
T
PathLike

Valid types for path values in "fs".

T
PathOrFileDescriptor
No documentation available
T
ReadPosition
No documentation available
T
StatsListener
No documentation available
T
TimeLike
No documentation available
T
WatchEventType
No documentation available
T
WatchListener
No documentation available
T
WriteFileOptions
No documentation available

Variables

v
constants.COPYFILE_EXCL

Constant for fs.copyFile. Flag indicating the destination file should not be overwritten if it already exists.

v
constants.COPYFILE_FICLONE

Constant for fs.copyFile. copy operation will attempt to create a copy-on-write reflink.If the underlying platform does not support copy-on-write, then a fallback copy mechanism is used.

v
constants.COPYFILE_FICLONE_FORCE

Constant for fs.copyFile. Copy operation will attempt to create a copy-on-write reflink.If the underlying platform does not support copy-on-write, then the operation will fail with an error.

v
constants.F_OK

Constant for fs.access(). File is visible to the calling process.

v
constants.O_APPEND

Constant for fs.open(). Flag indicating that data will be appended to the end of the file.

v
constants.O_CREAT

Constant for fs.open(). Flag indicating to create the file if it does not already exist.

v
constants.O_DIRECT

Constant for fs.open(). When set, an attempt will be made to minimize caching effects of file I/O.

v
constants.O_DIRECTORY

Constant for fs.open(). Flag indicating that the open should fail if the path is not a directory.

v
constants.O_DSYNC

Constant for fs.open(). Flag indicating that the file is opened for synchronous I/O with write operations waiting for data integrity.

v
constants.O_EXCL

Constant for fs.open(). Flag indicating that opening a file should fail if the O_CREAT flag is set and the file already exists.

v
constants.O_NOATIME

constant for fs.open().Flag indicating reading accesses to the file system will no longer result inan update to the atime information associated with the file.This flag is available on Linux operating systems only.

v
constants.O_NOCTTY

Constant for fs.open(). Flag indicating that if path identifies a terminal device,opening the path shall not cause that terminal to become the controlling terminal for the process(if the process does not already have one).

v
constants.O_NOFOLLOW

Constant for fs.open(). Flag indicating that the open should fail if the path is a symbolic link.

v
constants.O_NONBLOCK

Constant for fs.open(). Flag indicating to open the file in nonblocking mode when possible.

v
constants.O_RDONLY

Constant for fs.open(). Flag indicating to open a file for read-only access.

v
constants.O_RDWR

Constant for fs.open(). Flag indicating to open a file for read-write access.

v
constants.O_SYNC

Constant for fs.open(). Flag indicating that the file is opened for synchronous I/O.

v
constants.O_TRUNC

Constant for fs.open(). Flag indicating that if the file exists and is a regular file, and the file is opened successfully for write access, its length shall be truncated to zero.

v
constants.O_WRONLY

Constant for fs.open(). Flag indicating to open a file for write-only access.

v
constants.R_OK

Constant for fs.access(). File can be read by the calling process.

v
constants.S_IFBLK

Constant for fs.Stats mode property for determining a file's type. File type constant for a block-oriented device file.

v
constants.S_IFCHR

Constant for fs.Stats mode property for determining a file's type. File type constant for a character-oriented device file.

v
constants.S_IFDIR

Constant for fs.Stats mode property for determining a file's type. File type constant for a directory.

v
constants.S_IFIFO

Constant for fs.Stats mode property for determining a file's type. File type constant for a FIFO/pipe.

v
constants.S_IFLNK

Constant for fs.Stats mode property for determining a file's type. File type constant for a symbolic link.

v
constants.S_IFMT

Constant for fs.Stats mode property for determining a file's type. Bit mask used to extract the file type code.

v
constants.S_IFREG

Constant for fs.Stats mode property for determining a file's type. File type constant for a regular file.

v
constants.S_IFSOCK

Constant for fs.Stats mode property for determining a file's type. File type constant for a socket.

v
constants.S_IRGRP

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating readable by group.

v
constants.S_IROTH

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating readable by others.

v
constants.S_IRUSR

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating readable by owner.

v
constants.S_IRWXG

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating readable, writable and executable by group.

v
constants.S_IRWXO

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating readable, writable and executable by others.

v
constants.S_IRWXU

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating readable, writable and executable by owner.

v
constants.S_IWGRP

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating writable by group.

v
constants.S_IWOTH

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating writable by others.

v
constants.S_IWUSR

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating writable by owner.

v
constants.S_IXGRP

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating executable by group.

v
constants.S_IXOTH

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating executable by others.

v
constants.S_IXUSR

Constant for fs.Stats mode property for determining access permissions for a file. File mode indicating executable by owner.

v
constants.UV_FS_O_FILEMAP

When set, a memory file mapping is used to access the file. This flagis available on Windows operating systems only. On other operating systems,this flag is ignored.

v
constants.W_OK

Constant for fs.access(). File can be written by the calling process.

v
constants.X_OK

Constant for fs.access(). File can be executed by the calling process.

v
lstatSync

Synchronous lstat(2) - Get file status. Does not dereference symbolic links.

v
promises.constants
No documentation available
v
statSync

Synchronous stat(2) - Get file status.