How do I use graceful-fs in my Node.js project?

Simply require it as a drop-in replacement for the native fs module, like `var fs = require('graceful-fs')`, and use it for all filesystem operations. For global patching, call `gracefulFs.gracefulify(realFs)` at the top-level application layer only.

Does graceful-fs work with synchronous methods?

No, it cannot handle EMFILE or ENFILE errors for synchronous fs methods. The README explicitly states this is a known limitation, and developers are responsible for error handling in sync code.

What are the performance costs of using graceful-fs?

It prioritizes stability over speed by queuing operations to avoid errors, which can slow down filesystem access. This trade-off is intentional, as mentioned in the philosophy section of the README.

graceful-fs vs native fs: which should I choose?

Choose graceful-fs if you need automatic error handling for EMFILE, antivirus issues, or cross-platform consistency. Stick with native fs for maximum performance or if you only use synchronous methods and handle errors manually.

How to patch the global fs module with graceful-fs?

Use `gracefulFs.gracefulify(realFs)` at the application's top level, not in libraries, to avoid side-effects. This monkey-patches the fs module globally, but the README cautions against doing this in dependencies.

Is graceful-fs compatible with all Node.js versions?

It supports Node.js from 0.8 through 7.0 and likely beyond, but major version changes (e.g., v3 to v4) can be breaking due to shifts in patching approach, so check compatibility for your version.

graceful-fs — Node.js FS Error Handler

What is graceful-fs?

graceful-fs is a Node.js module that replaces the built-in fs module with enhanced error handling and cross-platform normalization. It makes filesystem operations more resilient by automatically retrying failed operations and queuing requests when system limits are reached, prioritizing application stability over speed.

Target Audience

Node.js developers building applications that perform intensive filesystem operations, especially those running on Windows with antivirus software or systems with file descriptor limits.

Value Proposition

Developers choose graceful-fs over the native fs module for its automatic handling of common filesystem errors (EMFILE, EACCESS, EAGAIN) and cross-platform consistency, preventing crashes from too many open files or antivirus interference without requiring manual error handling.

fs with incremental backoff on EMFILE

Use Cases

Best For

Applications that open many files simultaneously and risk hitting EMFILE/ENFILE errors from too many file descriptors.
Windows-based Node.js applications where antivirus software frequently locks files and blocks rename operations.
Cross-platform projects requiring consistent filesystem behavior across different operating systems and Node.js versions.
Legacy Node.js applications that need compatibility with older versions (pre-0.6.2) for methods like lchmod.
Applications where non-root users encounter EINVAL/EPERM errors during chown operations that should be ignored.
Projects using synchronous filesystem methods that cannot be automatically patched for EMFILE errors, requiring manual error handling.

Not Ideal For

Performance-critical applications where file I/O latency must be minimized, as queuing introduces delays.
Projects relying heavily on synchronous fs methods, since graceful-fs does not handle EMFILE errors for sync calls.
Libraries or modules that should avoid patching global fs to prevent side-effects on dependent code.
Environments requiring strict dependency stability, as major version changes can be breaking due to subtle behavior shifts.

Pros & Cons

Pros

Robust Error Handling

Automatically queues open and readdir calls on EMFILE errors, retrying them after file closures to prevent application crashes from too many open files.

Windows Antivirus Workaround

Retries rename operations for up to one second when blocked by antivirus software on Windows, reducing failures in common real-world scenarios.

Cross-Platform Consistency

Normalizes behavior for methods like lchmod and lutimes across different Node.js versions and operating systems, ensuring reliable filesystem access.

Non-Root User Tolerance

Ignores EINVAL and EPERM errors in chown operations for non-root users, avoiding unnecessary failures in permission-sensitive environments.

Cons

Sync Method Incompatibility

Cannot intercept or handle EMFILE/ENFILE errors for synchronous fs methods, requiring developers to manually handle errors in sync code, as noted in the README.

Performance Overhead

Trades EMFILE errors for slower filesystem operations by queuing requests, which can introduce latency not acceptable in high-performance applications.

Patching Side-Effects

Global patching via gracefulify can cause unexpected delays and behavior changes if used in libraries, as warned in the README caveats.

What is graceful-fs?

Target Audience

Node.js developers building applications that perform intensive filesystem operations, especially those running on Windows with antivirus software or systems with file descriptor limits.

Value Proposition

Use Cases

Best For

Applications that open many files simultaneously and risk hitting EMFILE/ENFILE errors from too many file descriptors.
Windows-based Node.js applications where antivirus software frequently locks files and blocks rename operations.
Cross-platform projects requiring consistent filesystem behavior across different operating systems and Node.js versions.
Legacy Node.js applications that need compatibility with older versions (pre-0.6.2) for methods like lchmod.
Applications where non-root users encounter EINVAL/EPERM errors during chown operations that should be ignored.
Projects using synchronous filesystem methods that cannot be automatically patched for EMFILE errors, requiring manual error handling.

Not Ideal For

Performance-critical applications where file I/O latency must be minimized, as queuing introduces delays.
Projects relying heavily on synchronous fs methods, since graceful-fs does not handle EMFILE errors for sync calls.
Libraries or modules that should avoid patching global fs to prevent side-effects on dependent code.
Environments requiring strict dependency stability, as major version changes can be breaking due to subtle behavior shifts.

Pros & Cons

Pros

Robust Error Handling

Automatically queues open and readdir calls on EMFILE errors, retrying them after file closures to prevent application crashes from too many open files.

Windows Antivirus Workaround

Retries rename operations for up to one second when blocked by antivirus software on Windows, reducing failures in common real-world scenarios.

Cross-Platform Consistency

Normalizes behavior for methods like lchmod and lutimes across different Node.js versions and operating systems, ensuring reliable filesystem access.

Non-Root User Tolerance

Ignores EINVAL and EPERM errors in chown operations for non-root users, avoiding unnecessary failures in permission-sensitive environments.

Cons

Sync Method Incompatibility

Cannot intercept or handle EMFILE/ENFILE errors for synchronous fs methods, requiring developers to manually handle errors in sync code, as noted in the README.

Performance Overhead

Trades EMFILE errors for slower filesystem operations by queuing requests, which can introduce latency not acceptable in high-performance applications.

Patching Side-Effects

Global patching via gracefulify can cause unexpected delays and behavior changes if used in libraries, as warned in the README caveats.

graceful-fs

What is graceful-fs?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

graceful-fs

What is graceful-fs?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?