Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.createReadStream() method

Reference for fs.createReadStream() in Node.js: read large files in chunks, choose a byte range with start and end, set encoding and highWaterMark.

fs.createReadStream(path[, options]) opens a file and returns a fs.ReadStream, a readable stream that delivers the content in chunks (64 KiB each by default). Memory use stays small no matter how large the file is, so it is the right tool for big files, for sending files over HTTP and for piping into compression or parsing.

The stream opens the file lazily and closes it for you when it ends, errors or is destroyed. You can read it with for await, with 'data' events, or connect it with pipeline().

NODE
import { createReadStream } from 'node:fs';

const stream = createReadStream('big.log', { encoding: 'utf8' });

Try it

Node.js Reading chunks with for await

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 A byte range, events and a missing file

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.createReadStream(path[, options]): fs.ReadStream

// options: string (encoding) | {
//   flags?: string,            // default 'r'
//   encoding?: string,         // default null (chunks are Buffers)
//   fd?: number | FileHandle,  // use an open descriptor instead of path
//   mode?: number,             // default 0o666
//   autoClose?: boolean,       // default true
//   emitClose?: boolean,       // default true
//   start?: number,
//   end?: number,              // default Infinity, inclusive
//   highWaterMark?: number,    // default 65536
//   signal?: AbortSignal,
//   fs?: object                // custom fs implementation
// }
Option Description
encoding If set, chunks are strings decoded safely across chunk boundaries; otherwise they are Buffers.
start, end Byte range to read, both inclusive and zero-based.
highWaterMark Size in bytes of each read. Larger values mean fewer, bigger chunks.
autoClose Close the descriptor on 'end' or 'error'. Leave this true.
fd Read from a descriptor you opened; then path is ignored and no 'open' event is emitted.
signal An AbortSignal that destroys the stream with an AbortError.

Returns: a fs.ReadStream. Extra members: path, bytesRead, pending (true until the file is open), plus the events 'open', 'ready' and 'close' on top of the normal stream events.

Errors: reported through the 'error' event, never thrown, for example ENOENT, EACCES, EISDIR. Wrong option types throw ERR_INVALID_ARG_TYPE immediately.

Usage notes

  • Handle 'error'. An unhandled error event crashes the process. stream.pipeline() and for await take care of this for you.
  • Chunks are not lines. A chunk can end in the middle of a line or a multi-byte character. Use the readline module, a transform, or encoding to get correct text.
  • Backpressure: pipe() and pipeline() pause the file reads while the destination is busy. Calling write() yourself in a 'data' handler ignores that.
  • end is inclusive. { start: 0, end: 9 } reads ten bytes. This differs from Array.slice. HTTP range requests (bytes=0-9) use the same convention.
  • Always release it: if you stop reading early, call stream.destroy() so the descriptor closes.
  • Whole file in memory? For small files readFile() is simpler. Streams pay off above a few megabytes or when you can process data as it arrives.
  • Alternative: filehandle.createReadStream() and filehandle.readableWebStream() exist for the promise API.