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().
import { createReadStream } from 'node:fs'; const stream = createReadStream('big.log', { encoding: 'utf8' });
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.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()andfor awaittake 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
readlinemodule, a transform, orencodingto get correct text. - Backpressure:
pipe()andpipeline()pause the file reads while the destination is busy. Callingwrite()yourself in a'data'handler ignores that. endis inclusive.{ start: 0, end: 9 }reads ten bytes. This differs fromArray.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()andfilehandle.readableWebStream()exist for the promise API.