<!--introduced_in=v0.10.0-->

<!--name=fs-->

The `fs` module provides an API for interacting with the file system in a

manner closely modeled around standard POSIX functions.

To use this module:

```js

const fs = require('fs');

```

All file system operations have synchronous and asynchronous forms.

The arguments passed to the completion callback depend on the method, but the

first argument is always reserved for an exception. If the operation was

completed successfully, then the first argument will be `null` or `undefined`.

```js

const fs = require('fs');

fs.unlink('/tmp/hello', (err) => {

if (err) throw err;

console.log('successfully deleted /tmp/hello');

});

```

Exceptions that occur using synchronous operations are thrown immediately and

may be handled using `try`/`catch`, or may be allowed to bubble up.

```js

const fs = require('fs');

try {

fs.unlinkSync('/tmp/hello');

console.log('successfully deleted /tmp/hello');

} catch (err) {

// handle the error

}

There is no guaranteed ordering when using asynchronous methods. So the

following is prone to error because the `fs.stat()` operation may complete

before the `fs.rename()` operation:

```js

fs.rename('/tmp/hello', '/tmp/world', (err) => {

if (err) throw err;

console.log('renamed complete');

});

fs.stat('/tmp/world', (err, stats) => {

if (err) throw err;

console.log(`stats: ${JSON.stringify(stats)}`);

});

```

To correctly order the operations, move the `fs.stat()` call into the callback

of the `fs.rename()` operation:

```js

fs.rename('/tmp/hello', '/tmp/world', (err) => {

if (err) throw err;

fs.stat('/tmp/world', (err, stats) => {

if (err) throw err;

console.log(`stats: ${JSON.stringify(stats)}`);

});

});

```

In busy processes, the programmer is _strongly encouraged_ to use the

asynchronous versions of these calls. The synchronous versions will block

While it is not recommended, most fs functions allow the callback argument to

be omitted, in which case a default callback is used that rethrows errors. To

get a trace to the original call site, set the `NODE_DEBUG` environment

variable:

Omitting the callback function on asynchronous fs functions is deprecated and

may result in an error being thrown in the future.

$ cat script.js

function bad() {

require('fs').readFile('/');

}

bad();

$ env NODE_DEBUG=fs node script.js

fs.js:88

throw backtrace;

^

Error: EISDIR: illegal operation on a directory, read

<stack trace.>

## File paths

Most `fs` operations accept filepaths that may be specified in the form of

a string, a [`Buffer`][], or a [`URL`][] object using the `file:` protocol.

String form paths are interpreted as UTF-8 character sequences identifying

the absolute or relative filename. Relative paths will be resolved relative

to the current working directory as specified by `process.cwd()`.

Example using an absolute path on POSIX:

```js

const fs = require('fs');

fs.open('/open/some/file.txt', 'r', (err, fd) => {

if (err) throw err;

fs.close(fd, (err) => {

if (err) throw err;

});

});

```

Example using a relative path on POSIX (relative to `process.cwd()`):

```js

fs.open('file.txt', 'r', (err, fd) => {

if (err) throw err;

fs.close(fd, (err) => {

if (err) throw err;

});

});

```

Paths specified using a [`Buffer`][] are useful primarily on certain POSIX

operating systems that treat file paths as opaque byte sequences. On such

systems, it is possible for a single file path to contain sub-sequences that

use multiple character encodings. As with string paths, `Buffer` paths may

be relative or absolute:

Example using an absolute path on POSIX:

```js

fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {

if (err) throw err;

fs.close(fd, (err) => {

if (err) throw err;

});

});

```

On Windows, Node.js follows the concept of per-drive working directory. This

behavior can be observed when using a drive path without a backslash. For

example `fs.readdirSync('c:\\')` can potentially return a different result than

`fs.readdirSync('c:')`. For more information, see

[this MSDN page][MSDN-Rel-Path].

<!-- YAML

added: v7.6.0

-->

For most `fs` module functions, the `path` or `filename` argument may be passed

as a WHATWG [`URL`][] object. Only [`URL`][] objects using the `file:` protocol

are supported.

```js

const fs = require('fs');

const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

```

Using WHATWG [`URL`][] objects might introduce platform-specific behaviors.

On Windows, `file:` URLs with a hostname convert to UNC paths, while `file:`

URLs with drive letters convert to local absolute paths. `file:` URLs without a

```js

// On Windows :

// - WHATWG file URLs with hostname convert to UNC path

// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file

fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - WHATWG file URLs with drive letters convert to absolute path

// file:///C:/tmp/hello => C:\tmp\hello

fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - WHATWG file URLs without hostname must have a drive letters

fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));

fs.readFileSync(new URL('file:///c/p/a/t/h/file'));

// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

```

the drive letter. Using another separator will result in a throw.

On all other platforms, `file:` URLs with a hostname are unsupported and will

result in a throw:

```js

// On other platforms:

// - WHATWG file URLs with hostname are unsupported

// file://hostname/p/a/t/h/file => throw!

fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG file URLs convert to absolute path

// file:///tmp/hello => /tmp/hello

fs.readFileSync(new URL('file:///tmp/hello'));

```

A `file:` URL having encoded slash characters will result in a throw on all

platforms:

```js

// On Windows

fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));

fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));

/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded

\ or / characters */

// On POSIX

fs.readFileSync(new URL('file:///p/a/t/h/%2F'));

fs.readFileSync(new URL('file:///p/a/t/h/%2f'));

/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded

/ characters */

```

On Windows, `file:` URLs having encoded backslash will result in a throw:

```js

// On Windows

fs.readFileSync(new URL('file:///C:/path/%5C'));

fs.readFileSync(new URL('file:///C:/path/%5c'));

/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded

\ or / characters */

```

## File Descriptors

On POSIX systems, for every process, the kernel maintains a table of currently

open files and resources. Each open file is assigned a simple numeric

identifier called a *file descriptor*. At the system-level, all file system

operations use these file descriptors to identify and track each specific

file. Windows systems use a different but conceptually similar mechanism for

tracking resources. To simplify things for users, Node.js abstracts away the

specific differences between operating systems and assigns all open files a

numeric file descriptor.

The `fs.open()` method is used to allocate a new file descriptor. Once

allocated, the file descriptor may be used to read data from, write data to,

or request information about the file.

```js

fs.open('/open/some/file.txt', 'r', (err, fd) => {

if (err) throw err;

fs.fstat(fd, (err, stat) => {

if (err) throw err;

// use stat

// always close the file descriptor!

fs.close(fd, (err) => {

if (err) throw err;

});

});

});

```

Most operating systems limit the number of file descriptors that may be open

at any given time so it is critical to close the descriptor when operations

are completed. Failure to do so will result in a memory leak that will

eventually cause an application to crash.

## Threadpool Usage

All file system APIs except `fs.FSWatcher()` and those that are explicitly

synchronous use libuv's threadpool, which can have surprising and negative

performance implications for some applications. See the

<!-- YAML

added: v0.5.8

-->

A successful call to [`fs.watch()`][] method will return a new `fs.FSWatcher`

object.

All `fs.FSWatcher` objects are [`EventEmitter`][]'s that will emit a `'change'`

event whenever a specific watched file is modified.

<!-- YAML

added: v0.5.8

-->

The `filename` argument may not be provided depending on operating system

support. If `filename` is provided, it will be provided as a `Buffer` if

```js

console.log(filename);

// Prints: <Buffer ...>

});

```

### Event: 'close'

<!-- YAML

-->

Emitted when the watcher stops watching for changes. The closed

`fs.FSWatcher` object is no longer usable in the event handler.

<!-- YAML

added: v0.5.8

-->

Emitted when an error occurs while watching the file. The errored

`fs.FSWatcher` object is no longer usable in the event handler.

<!-- YAML

added: v0.5.8

-->

Stop watching for changes on the given `fs.FSWatcher`. Once stopped, the

`fs.FSWatcher` object is no longer usable.

<!-- YAML

added: v0.1.93

-->

A successful call to `fs.createReadStream()` will return a new `fs.ReadStream`

object.

All `fs.ReadStream` objects are [Readable Streams][].

<!-- YAML

added: v0.1.93

-->

<!-- YAML

added: v0.1.93

-->

### Event: 'ready'

<!-- YAML

added: v9.11.0

-->

Emitted when the `fs.ReadStream` is ready to be used.

Fires immediately after `'open'`.

### readStream.bytesRead

<!-- YAML

-->

The number of bytes that have been read so far.

<!-- YAML

added: v0.1.93

-->

The path to the file the stream is reading from as specified in the first

argument to `fs.createReadStream()`. If `path` is passed as a string, then

`readStream.path` will be a string. If `path` is passed as a `Buffer`, then

`readStream.path` will be a `Buffer`.

<!-- YAML

added: v0.1.21

pr-url: https://github.com/nodejs/node/pull/13173

description: Added times as numbers.

A `fs.Stats` object provides information about a file.

Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and

their synchronous counterparts are of this type.

If `bigint` in the `options` passed to those methods is true, the numeric values

will be `bigint` instead of `number`.

dev: 2114,

ino: 48064969,

mode: 33188,

nlink: 1,

uid: 85,

gid: 100,

rdev: 0,

size: 527,

blksize: 4096,

blocks: 8,

atimeMs: 1318289051000.1,

mtimeMs: 1318289051000.1,

ctimeMs: 1318289051000.1,

birthtimeMs: 1318289051000.1,

atime: Mon, 10 Oct 2011 23:24:11 GMT,

mtime: Mon, 10 Oct 2011 23:24:11 GMT,

ctime: Mon, 10 Oct 2011 23:24:11 GMT,

`bigint` version:

```console

Stats {

dev: 2114n,

ino: 48064969n,

mode: 33188n,

nlink: 1n,

uid: 85n,

gid: 100n,

rdev: 0n,

size: 527n,

blksize: 4096n,

blocks: 8n,

atimeMs: 1318289051000n,

mtimeMs: 1318289051000n,

ctimeMs: 1318289051000n,

birthtimeMs: 1318289051000n,

atime: Mon, 10 Oct 2011 23:24:11 GMT,

mtime: Mon, 10 Oct 2011 23:24:11 GMT,

ctime: Mon, 10 Oct 2011 23:24:11 GMT,

birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

```

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a block device.

### stats.isCharacterDevice()

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a character device.

### stats.isDirectory()

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a file system directory.

### stats.isFIFO()

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a first-in-first-out (FIFO)

pipe.

### stats.isFile()

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a regular file.

### stats.isSocket()

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a socket.

### stats.isSymbolicLink()

<!-- YAML

added: v0.1.10

-->

* Returns: {boolean}

Returns `true` if the `fs.Stats` object describes a symbolic link.

### stats.dev

The numeric identifier of the device containing the file.

### stats.ino

The file system specific "Inode" number for the file.

### stats.mode

A bit-field describing the file type and mode.

### stats.nlink

The number of hard-links that exist for the file.

### stats.uid