Skip to content
Package50 repository health

fsnotify

A Go library that delivers cross-platform filesystem change notifications through a single Watcher API backed by native OS event mechanisms.

Library Govv1.10.110,812 stars BSD 3-Clause License
go get github.com/fsnotify/fsnotify
View source

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Fair
  • Development activity4
  • Maintenance20
  • Community76
  • Maturity60
  • Momentum40

Technical analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →
Excellent
  • Architecture85
  • Code quality85
  • Innovation82
  • Learning curve80

fsnotify wraps the filesystem-change primitives of Linux (inotify), macOS/BSD (kqueue), Windows (ReadDirectoryChangesW), and illumos (FEN) behind one consistent Go API: create a Watcher, add paths, and read Create/Write/Remove/Rename/Chmod events off a channel. It has been the de facto standard for filesystem watching in the Go ecosystem for over a decade and sits as an indirect dependency inside a huge share of the Go tooling landscape — build tools, hot-reloaders, config watchers, and CLI utilities.

The library deliberately stays small: no recursive watching, no polling fallback, no bundled debouncing. Instead it gives callers a thin, predictable layer over what each operating system actually reports, along with extensive documentation of the platform-specific quirks (rename cookies, Chmod-before-Remove ordering on Linux, kqueue file-descriptor limits) that trip up naive implementations. Consumers who need higher-level behavior like recursive watches or event coalescing are expected to build it on top.

What You Get

  • A Watcher type with Add/AddWith/Remove/Close/WatchList methods and buffered or unbuffered Events/Errors channels
  • A unified Op bitmask (Create, Write, Remove, Rename, Chmod) that normalizes each OS’s native event vocabulary
  • Per-platform backends (inotify, kqueue, ReadDirectoryChangesW, FEN) selected automatically at build time via Go build tags
  • AddWith/WithBufferSize for tuning the Windows event buffer when large bursts risk overflow
  • FSNOTIFY_DEBUG=1 environment-variable support that prints every raw platform event to stderr for troubleshooting
  • Extensive documented platform notes covering rename-cookie pairing, Linux’s Chmod-before-Remove ordering, and kqueue file-descriptor exhaustion

Common Use Cases

  • Hot-reloading build tools - watch source files and trigger a rebuild or live-reload on Write/Create events, the pattern used by many Go-based dev servers and static-site generators
  • Configuration hot-reload - watch a config file’s parent directory and re-read settings when editors atomically replace the file via a Rename
  • File-sync and backup daemons - detect Create/Remove/Rename events in a watched tree to queue sync operations without polling
  • Log and data pipeline tailers - notice when new files appear in a spool directory and start processing them immediately
  • Editor and IDE tooling - detect external file changes (e.g. git checkout, formatter output) to refresh in-memory buffers or trigger diagnostics

Under The Hood

Architecture

fsnotify is organized around one exported Watcher struct that embeds a backend interface (Add, AddWith, Remove, WatchList, Close, xSupports) defined in fsnotify.go; the concrete implementation is chosen entirely at compile time through Go build tags, with backend_inotify.go (//go:build linux), backend_kqueue.go (macOS/BSD), backend_windows.go, and backend_fen.go (illumos) each providing their own struct that satisfies that interface and embeds a shared *shared helper type for common bookkeeping like watch bookkeeping and channel wiring. This keeps the public surface (NewWatcher, Add, Events, Errors, Close) identical across platforms while letting each backend manage OS-specific state — inotify’s rename-cookie LRU cache, kqueue’s per-file descriptor table, Windows’s overlapped I/O buffer — internally. Because the abstraction boundary is a plain Go interface rather than a runtime dispatch table, swapping or extending a backend only touches its own file; the core fsnotify.go and internal/ package never need to know which OS backend is active.

Tech Stack

The module (go.mod) targets Go 1.23+ and declares a single external dependency, golang.org/x/sys, used for the raw syscalls each backend needs (unix.InotifyInit1, kqueue’s Kevent, and Windows’s ReadDirectoryChangesW bindings). Everything else — event dispatch, the Op bitmask, buffer management — is standard library only (os, path/filepath, sync, errors). There is no build system beyond go build/go test; CI (.github/workflows/test.yml and staticcheck.yml) runs the test suite and staticcheck linting across the supported platforms rather than relying on any bundled task runner.

Code Quality

Each backend ships its own dedicated test file (backend_inotify_test.go, backend_kqueue_test.go, backend_windows_test.go, backend_fen_test.go) alongside shared cross-platform tests in fsnotify_test.go, helpers_test.go, and a synctest_test.go that exercises timing-sensitive event ordering. Error handling favors typed sentinel errors (ErrNonExistentWatch, ErrClosed, ErrEventOverflow) returned explicitly rather than panics or swallowed failures, and public functions/types carry substantial godoc comments explaining platform edge cases inline. A staticcheck.conf plus a dedicated CI lint workflow enforce static analysis on every push, and naming is consistently idiomatic Go (exported Watcher/Event/Op, unexported watchFlag, koekje cookie helper).

API Design The public surface is deliberately minimal: construct a Watcher, call Add(path), and range over two channels — there’s no configuration object to assemble and no callback registration boilerplate. Op is a bitmask with a Has() helper so callers avoid brittle equality checks against multi-flag events, and the one platform-specific knob (WithBufferSize for Windows) is opt-in via a functional-options pattern (AddWith) rather than cluttering the common path. The tradeoff for this simplicity is that callers must implement their own recursion and debouncing, which the README states explicitly rather than leaving undocumented — the FAQ and platform-notes sections in the docs preempt the most common integration mistakes (watching individual files, NFS/FUSE limitations, Chmod noise).

Used by 22 apps in this directory

Every app whose dependencies include github.com/fsnotify/fsnotify, nine to a page.

Showing 22 apps
Go 73%GPL 3.0

1Panel

37,480

Devops · Hosting Control Panel · Monitoring

The only open-source VPS control panel with native AI agent runtime — deploy websites, Docker stacks, and local LLMs from one web interface.

App
Built with
  • Go 73%
  • Vue 27%
Updated yesterdayView details
TypeScript 50%Apache 2.0

agent-orchestrator

14,975

AI Agents · AI Code Assistants · Developer Tools

A local desktop workspace that gives every coding task its own agent, Git branch, and worktree, then tracks tasks, pull requests, CI, and reviews for 27 coding agents on one live Kanban board.

App
Built with
  • TypeScript 50%
  • Go 48%
Updated todayView details
Go 86%Apache 2.0

Argo Workflows

17,108

Data Engineering · Devops

The most popular Kubernetes-native workflow engine for orchestrating containerized DAGs, ML pipelines, CI/CD, and parallel batch jobs at scale.

App
Built with
  • Go 86%
  • TypeScript 10%
Updated todayView details
Go 83%Apache 2.0

Authelia

29,692

Authentication · Security

OpenID Certified SSO and MFA portal for securing self-hosted web applications behind reverse proxies.

App
Built with
  • Go 83%
  • TypeScript 15%
Updated todayView details
Go 58%Apache 2.0

Authgear

2,158

Authentication

Open-source, self-hostable authentication platform with passkeys, biometric login, SSO, MFA, and GraphQL admin API — a full Auth0/Clerk/Firebase alternative for SaaS and mobile apps.

App
Built with
  • Go 58%
  • HTML 20%
  • TypeScript 19%
Updated yesterdayView details
Go 92%AGPL 3.0

BillionMail

16,441

Marketing

Self-hosted email server and marketing platform that gives you unlimited sending, full deliverability control, and AI-assisted campaigns without monthly fees.

App
Built with
  • Go 92%
Updated 5 months agoView details
TypeScript 55%MIT

Bytebase

14,721

Devops

An open-source database CI/CD and DevSecOps platform — schema migration review, GitOps-driven changes, data masking, and access control across MySQL, PostgreSQL, Oracle, Snowflake, MongoDB, and more.

App
Built with
  • TypeScript 55%
  • Go 39%
Updated todayView details
Go 74%AGPL 3.0

Coder

17,450

Code Editors · Developer Tools · Devops

Self-hosted cloud development environments and AI coding agents — defined in Terraform, connected via WireGuard, automatically shut down when idle.

App
Built with
  • Go 74%
  • TypeScript 24%
Updated todayView details
Go 36%Apache 2.0

CubeSandbox

13,391

AI Agents · Developer Tools · Security

Instant, concurrent, hardware-isolated MicroVM sandboxes for AI agents — E2B-API compatible, sub-60ms cold starts, and a built-in zero-trust egress proxy, all self-hostable at scale.

App
Built with
  • Go 36%
  • Rust 23%
  • C 20%
Updated todayView details

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers