NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io
crates.io, #5007 most downloaded on crates.io
Library to execute commands in response to file modifications
Latest stable
8.4.4
Last release 1 months ago
06 Oct 2026
Release timing varies
gaps range from 2 weeks to 9 months
Most releases are documented
notes for 50 of the last 60 stable releases
7 versions withdrawn
withdrawn after publishing
10 years old
84 releases · first in 2016
Drag across the ruler to compare, or tap a release to open it.
chore: Release package watchexec version 8.4.4
chore: Release package watchexec version 8.4.4
chore: Release package watchexec version 8.4.3
chore: Release package watchexec version 8.4.3
chore: Release package watchexec version 8.4.2
chore: Release package watchexec version 8.4.2
Your coding agent can read these notes before it upgrades. Set up the MCP server →
chore: Release package watchexec version 8.4.1
chore: Release package watchexec version 8.4.1
chore: Release package watchexec version 8.4.0
chore: Release package watchexec version 8.4.0
Filterer::check_dir and Watchexec-owned, source-filtered recursion for Inotify, Windows ReadDirectoryChanges, and Poll backends.fs_ready now reports settled reconciliation and may signal after partial nonfatal failures.FSEvents without rebuilding its shared stream.chore: Release package watchexec version 8.3.0
Feat: add fs_ready signal for watcher readiness
fs_ready signal for watcher readiness (#1024)Nothing published for this version
Fix: bug on macOS where a task in the keyboard events worker would hang after graceful quit
Augments keyboard_events config to emit events for all single keyboard key inputs, in addition to the existing EOF
keyboard_events config to emit events for all single keyboard key inputs, in addition to the existing EOFkeyboard_events now switches to raw mode (and disabling it switches back to cooked)Nothing published for this version
Nothing published for this version
Nothing published for this version
- Deps: nix 0.29
Feature: non-recursive watches with WatchedPath::non_recursive()
WatchedPath::non_recursive()config.pathset() now preserves WatchedPath attributesWatchedPath to the root of the crate (old path remains as re-export for now)Deps: replace command-group with process-wrap (in supervisor, but has flow-on effects)
Deps: watchexec-events and watchexec-signals after major bump and yank
Deprecated items (mostly leftover from splitting out the watchexec_events and watchexec_signals crates) are removed.
Watchexec the core experience rather than providing the kitchensink / components so you could build your own from the pieces; that helps the cohesion of the whole and simplifies many patterns.watchexec_events and watchexec_signals crates) are removed.watchexec-supervisor.WatchexecWatchexec::new() now takes the on_action handler. As this is the most important handler to define and Watchexec will not be functional without one, that enforces providing it first.Watchexec::with_config() lets one provide a config upfront, otherwise the default values are used.Watchexec::default() is mostly used to avoid boilerplate in doc comment examples, and panics on initialisation errors.Watchexec::reconfigure() is removed. Use the public config field instead to access the "live" Arc<Config> (see below).Job#to_wait instead. Of course you can insert them as synthetic events if you want.InitConfig and RuntimeConfig have been unified into a single Config struct.WorkingData structures, all of the config is now flat in the same Config. That makes it easier to work with as all that's needed is to pass an Arc<Config> around, but it does mean the event sources are no longer independent.tokio::sync::watch for some values, and HandlerLock for handlers, and so on, everything is now a new Changeable type, specialised to ChangeableFn for closures and ChangeableFilterer for the Filterer.signal_change() method which must be called after changes to the config; this is taken care of when using the methods on Config. This is required for the few places in Watchexec which need active reconfiguration rather than reading config values just-in-time.Watchexec::reconfigure() and keeping a clone of the config around, an Arc<Config> is now "live" and changes applied to it will affect the Watchexec instance directly.command / commands are removed from config. Instead use the Action handler API for creating new supervised commands.command_grouped is removed from config. That's now an option set on Command.action_throttle is renamed to throttle and now defaults to 50ms, which is the default in Watchexec CLI.keyboard_emit_eof is renamed to keyboard_events.pre_spawn_handler is removed. Use Job#set_spawn_hook instead.post_spawn_handler is removed. Use Job#run instead.The structure has been reworked to be simpler and more extensible. Instead of a Command enum, there's now a Command struct, which holds a single Program and behaviour-altering options. Shell has also been redone, with less special-casing.
If you had:
Command::Exec {
prog: "date".into(),
args: vec!["+%s".into()],
}
You should now write:
Command {
program: Program::Exec {
prog: "date".into(),
args: vec!["+%s".into()],
},
options: Default::default(),
}
The new Program::Shell field args: Vec<String> lets you pass (trailing) arguments to the shell invocation:
Program::Shell {
shell: Shell::new("sh"),
command: "ls".into(),
args: vec!["--".into(), "movies".into()],
}
is equivalent to:
$ sh -c "ls" -- movies
args field of Command::Shell is now the options field of Shell.Shell has a new field program_option: Option<Cow<OsStr>> which is the syntax of the option used to provide the command. Ie for most shells it's -c and for CMD.EXE it's /C; this makes it fully customisable (including its absence!) if you want to use weird shells or non-shell programs as shells.Shell::Powershell is removed.raw_arg instead of arg to avoid quoting issues.Command can no longer take a list of programs. That was always quite a hack; now that multiple supervised commands are possible, that's how multiple programs should be handled.command_grouped option is now Command-level, so you can start both grouped and non-grouped programs.reset_sigmask option to control whether commands should have their signal masks reset on Unix. By default the signal mask is inherited.RuntimeError::NoCommands, RuntimeError::Handler, RuntimeError::HandlerLockHeld, and CriticalError::MissingHandler are removed as the relevant types/structures don't exist anymore.RuntimeError::CommandShellEmptyCommand and RuntimeError::CommandShellEmptyShell are removed; you can construct Shell with empty shell program and Program::Shell with an empty command, these will at best do nothing but they won't error early through Watchexec.RuntimeError::ClearScreen is removed, as clearing the screen is now done by the consumer of Watchexec, not Watchexec itself.RuntimeErrors, and are now CriticalErrors. These being runtime, nominally recoverable errors instead of end-the-world failures is one of the most common pitfalls of using the library, and though recovery is technically possible, it's better approached other ways.on_error handler is now sync only and no longer returns a Result; as such there's no longer the weird logic of "if the on_error handler errors, it will call itself on the error once, then crash".on_error, you should instead use non-async calls (like try_send() for Tokio channels). The error handler is expected to return as fast as possible, and not do blocking work if it can at all avoid it; this was always the case but is now documented more explicitly.The process supervision system is entirely reworked. Instead of "applying Outcomes", there's now a Job type which is a single supervised command, provided by the separate watchexec-supervisor crate. The Action handler itself can only create new jobs and list existing ones, and interaction with commands is done through the Job type.
The controls available on Job are now modeled on "real" supervisors like systemd, and are both more and less powerful than the old Outcome system. This can be seen clearly in how a "restart" is specified. Previously, this was an Outcome combinator:
Outcome::if_running(
Outcome::both(Outcome::stop(), Outcome::start()),
Outcome::start(),
)
Now, it's a discrete method:
job.restart();
Previously, a graceful stop was a mess:
Outcome::if_running(
Outcome::both(
Outcome::both(
Outcome::signal(Signal::Terminate),
Outcome::wait_timeout(Duration::from_secs(30)),
),
Outcome::both(Outcome::stop(), Outcome::start()),
),
Outcome::DoNothing,
)
Now, it's again a discrete method:
job.stop_with_signal(Signal::Terminate, Duration::from_secs(30));
The stop() and start() methods also do nothing if the process is already stopped or started, respectively, so you don't need to check the status of the job before calling them. The try_restart() method is available to do a restart only if the job is running, with the try_restart_with_signal() variant for graceful restarts.
Further, all of these methods are non-blocking sync (and take &self), but they return a Ticket, a future which resolves when the control has been processed. That can be dropped if you don't care about it without affecting the job, or used to perform more advanced flow control. The special to_wait() method returns a detached, cloneable, "wait()" future, which will resolve when the process exits, without needing to hold on to the Job or a reference at all.
See the restart_run_on_successful_build example which starts a cargo build, waits for it to end, and then (re)starts cargo run if the build exited successfully.
Finally: Outcome::Clear and Outcome::Reset are gone, and there's no equivalent on Job: that's because these are screen control actions, not job control. You should use the clearscreen crate directly in your action handler, in conjunction with job control, to achieve the desired effect.
Change the --wrap-process default on Mac to pre-1.24 behaviour (session, instead of group).
Change the --wrap-process default on Mac to pre-1.24 behaviour (session, instead of group).
Please chime in #864 if that breaks your usage.
Internal dependency updates, no changed functionality.
Internal dependency updates, no changed functionality.
Zero-value unitless time spans are no longer deprecated
--help--filter-prog is no longer experimental (won't warn on use)--only-emit-events now implies --emit-events-to=json-stdio--socket (#905)This implements the systemd socket-passing protocol, like a lightweight systemfd: sockets are opened from the watchexec process, and then passed to the commands it runs. This lets you keep sockets open and avoid address reuse issues or dropping packets.
The value can be either of PORT (opens a TCP listening socket at that port), HOST:PORT (specify a host IP address; IPv6 addresses can be specified [bracketed]), TYPE::PORT or TYPE::HOST:PORT (specify a socket type, tcp / udp). This syntax and the behaviour of this option is compatible with systemfd's.
This integration only provides basic support, if you want more control you should use the systemfd tool from @mitsuhiko directly. To make use of the sockets in Rust code, you can use the listenfd crate, also by Armin.
I've also written a document that describes the minimal protocol, if you want to see how to use it in your projects or how to implement it yourself, both for Unix (systemd's invention) and for Windows (systemfd's invention): https://github.com/watchexec/watchexec/blob/main/doc/socket.md
Explicitly watching files that are in your .gitignore no longer requires --no-vcs-ignore (#674, #859, contributed by @TheBlek)
--no-vcs-ignore (#674, #859, contributed by @TheBlek)rust-version indication will remain, for the minimum estimated Rust version for the code features used in the crate's own code, but dependencies may have already moved on. From now on, only latest stable is assumed and tested for. (#510)watchexec-events and watchexec-signals crates.SubSignal and MainSignal into a new Signal type. The former types and paths exist as deprecated aliases/re-exports.Regression: -w, --watch was accidentally set to behave as -W
-w, --watch was accidentally set to behave as -W (#828)New: -W, --watch-non-recursive for watching paths without also watching subfolders.
-W, --watch-non-recursive for watching paths without also watching subfolders..git is a file rather than a folder)libc on Unix.dunce, replaced with either Tokio's canonicalize (properly async) or normalize-path (performs no I/O).#[must_use] annotations to a bunch of functions.Send bound to HandlerLock.summarise_events_to_env on Windows to output paths with backslashes.- Deps: upgrade to miette 5.3.0
- Deps: upgrade to Notify 5.0.0
The idea, however, is to start a new era of Watchexec releases, where breaking changes are allowed more easily (to give an idea of how breaking-change…
This is the first breaking release. Most of it is cleaning up a number of deprecated options, and changing some defaults. The idea, however, is to start a new era of Watchexec releases, where breaking changes are allowed more easily (to give an idea of how breaking-change-averse the project has been: this release was planned in January 2022! and ever-delayed since).
Fear not! The cadence of breaking releases will be at most once or twice a year, and whenever possible a deprecation will precede a break by at least three months. Watchexec will remain a stable part of your workflow, while allowing ourselves some evolution.
$SHELL when it is present. (#210)
Use --shell=sh to switch back if your $SHELL is something else.--shell=cmd to switch back to CMD.EXE, or set the SHELL environment variable.
A reminder that Windows 7 is not supported, and hasn't been for years.--on-busy-update defaults to do-nothing now (was queue).
Events received while a command is running won't trigger a run of the command immediately following this one.-W / --watch-when-idle is removed, as it is now the default.--stop-timeout is now 10 seconds.--debounce, --delay-run, --poll, and --stop-timeout now prefer durations with a unit, and warn if given unit-less durations. The default units for these are millisecond for --debounce and --poll, and seconds for --delay-run and --stop-timeout, which is a source of confusion. Unit-less durations will be removed in a future breaking release.--no-shell is removed.
Use --shell=none instead. The -n short option remains as an alias to --shell=none.-k / --kill is removed.
Use --signal=KILL instead.--changes-only is removed.
Use --print-events instead.--emit-events-to defaults to none, and the environment mode is deprecated.--emit-events-to no longer accepts stdin (deprecated alias for stdio) and json-stdin(deprecated alias for json-stdio).--no-ignore is removed.
Use --no-project-ignore instead.--no-environment is deprecated.--clear=reset will reset the screen on graceful shutdown. (#797)--no-process-group is deprecated.WATCHEXEC_FILTERER environment variable.--wrap-process=MODE lets you choose between using process groups, process sessions, or nothing at all. (#794)WATCHEXEC_TMPDIR environment variable can be used to customize where Watchexec will write temporary files, if for some reason your $TMPDIR is unwritable. (#814)As a treat, this release also features an experimental new option: -j or --filter-prog, which lets you write filter programs.
-j, --filter-prog EXPRESSIONProvide your own custom filter programs in jaq (similar to jq) syntax. Programs are given an event in the same format as described in --emit-events-to and must return a boolean. In addition to the jaq stdlib, watchexec adds some custom filter definitions:
path | file_meta returns file metadata or null if the file does not exist.path | file_size returns the size of the file at path, or null if it does not exist.path | file_read(bytes) returns a string with the first n bytes of the file at path. If the file is smaller than n bytes, the whole file is returned. There is no filter to read the whole file at once to encourage limiting the amount of data read and processed.string | hash, and path | file_hash return the hash of the string or file at path. No guarantee is made about the algorithm used: treat it as an opaque value.any | kv_store(key), kv_fetch(key), and kv_clear provide a simple key-value store. Data is kept in memory only, there is no persistence. Consistency is not guaranteed.any | printout, any | printerr, and any | log(level) will print or log any given value to stdout, stderr, or the log (levels = error, warn, info, debug, trace), and pass the value through (so [1] | log("debug") | .[] will produce a 1 and log [1]).All filtering done with such programs, and especially those using kv or filesystem access, is much slower than the other filtering methods. If filtering is too slow, events will back up and stall watchexec. Take care when designing your filters.
If the argument to this option starts with an '@', the rest of the argument is taken to be the path to a file containing a jaq program.
Jaq programs are run in order, after all other filters, and short-circuit: if a filter (jaq or not) rejects an event, execution stops there, and no other filters are run. Additionally, they stop after outputting the first value, so you'll want to use 'any' or 'all' when iterating, otherwise only the first item will be processed, which can be quite confusing!
Regexp ignore filter on paths:
all(.tags[] | select(.kind == "path"); .absolute | test("[.]test[.]js$")) | not
Pass any event that creates a file:
any(.tags[] | select(.kind == "fs"); .simple == "create")
Pass events that touch executable files:
any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | metadata | .executable)
Ignore files that start with shebangs:
any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | read(2) == "#!") | not
More examples can be found and contributed in the discussion thread
First "stable" release of the library.
Change: the library is split into even more crates
project-origins and ignore-files, extract standalone functionalitycommand-group and clearscreenChange: the Action worker now launches a set of Commands
Command replaces and augments Shell, making explicit which style of calling will be usedVec<Command>, so multiple commands to be run as a setPreSpawn and PostSpawn handlers are run per Command, not per command setcmd1 && cmd2Change: the event queue is now a priority queue
on_action to do anythingFilterer trait changes slightly to let filterers use event priorityImprovement: the main subtasks of the runtime are now aborted on error
Improvement: the event queue is explicitly closed when shutting down
Improvement: the action worker will check if the event queue is closed more often, to shutdown early
Improvement: kill_on_drop is set on Commands, which will be a little more eager to terminate processes when we're done with them
Feature: Outcome::Sleep waits for a given duration (#79)
Other miscellaneous:
Deps: add the log feature to tracing so logs can be emitted to log subscribers
Deps: upgrade to Tokio 1.19
Deps: upgrade to Miette 4
Deps: upgrade to Notify 5.0.0-pre.15
Docs: fix the main example in lib.rs (#297)
Docs: describe a tuple argument in the globset filterer interface
Docs: the library crate gains a file-based CHANGELOG.md (and won't go in the Github releases tab anymore)
Docs: the library's readme's code block example is now checked as a doc-test
Meta: PRs are now merged by Bors
Replace git2 dependency by git-config (#267). This makes using the library more pleasant and will also avoid library version mismatch errors when the
Revert backend switch on mac from previous release. We'll do it a different way later
Internal change: kqueue backend is used on mac. This _should_ reduce or eliminate some old persistent bugs on mac, and improve response times, but ple
Watchexec::new() now reports the library's version at debug level=) requirement, to avoid breakage (#266)New error::FsWatcherError enum split off from RuntimeError, and with additional variants to take advantage of targeted help text for known inotify err
error::FsWatcherError enum split off from RuntimeError, and with additional variants to take advantage of targeted help text for known inotify errors on Linuxextensions and filters are now cooperative rather than exclusionary. That is, a filters of ["Gemfile"] and an extensions of ["js", "rb"] will match both Gemfile and index.js rather than matching nothing at all. This restores pre 2.0 behaviour.*/file will match both file and dir/file instead of just dir/file. This is a compatibility fix and is incorrect behaviour which will be removed in the future. Do not rely on it.The on_error handler gets an upgraded parameter which lets it upgrade (runtime) errors to critical.
on_error handler gets an upgraded parameter which lets it upgrade (runtime) errors to critical.summarize_events_to_paths now deduplicates paths within each variable.Action, PreSpawn, and PostSpawn structs passed to handlers now contain an Arc<[Event]> instead of an Arc >
Fix: globset filterer should pass all non-path events
Pre-release Pre-release Compare
Pre-release
Pre-release
Compare
Yanked for critical bug in globset filterer (fixed in pre.8) on 2022-01-26
First version of library v2 that was used in a CLI release.
First version of library v2 that was used in a CLI release.
Update MSRV (to 1.58) and policy (bump incurs minor semver only)
More logging, especially around ignore file discovery and filtering
paths::PATH_SEPARATOR is now public, being : on Unix and ; and Windows.`summarise_events_to_env` used to return COMMON_PATH, it now returns COMMON, in keeping with the other variable names.
summarise_events_to_env used to return COMMON_PATH, it now returns COMMON, in keeping with the other variable names.`summarise_events_to_env` returns a HashMap<&str, OsString> rather than HashMap<&OsStr, OsString>, because the expectation is that the variable names
summarise_events_to_env returns a HashMap<&str, OsString> rather than HashMap<&OsStr, OsString>, because the expectation is that the variable names are processed, e.g. in the CLI: WATCHEXEC_{}_PATH. OsStr makes that painful for no reason (the strings are static anyway).Action struct's events field changes to be an Arc<Vec<Event>> rather than a Vec<Event>: the intent is for the events to be immutable/read-only (and it also made it easier/cheaper to implement the next change below).PreSpawn and PostSpawn structs got a new events: Arc<Vec<Event>> field so these handlers get read-only access to the events that triggered the command.More documentation around tagged filterer:
== and != are case-insensitiveFileTypeProcessEnd (ExitStatus replacement)Placeholder release of v2 library (preview)
Nothing published for this version
Process handling code replaced with the new command-group crate.
use_process_group (default true) allows disabling use of process groups.cargo install watchexec stub removed.Nothing published for this version
`ba26999` Pin globset to 0.4.6 to avoid breakage due to a bugfix in 0.4.7
Initial release as a separate crate.
- #191 Bugfix: Type change caused a warning message to have dupe info. - #192 Bugfix: Windows critical on some (?) versions of Win10 due to XML schema
New: a cute logo for the project! 🐚🦀 This is used in the repo metadata and the API documentation. For now!
clearscreen which is a comprehensive terminal/console screen clearing library. Eventually this will be used here, for now it needs a little time to settle and get properly tested around a bunch of terminals and setups (and you can help!). However, its API is stable and it is fully documented, so please consider it for new projects!Manpage is built in HTML as well as Roff and included in releases (more useful than roff on windows).
Add --shell=SHELL and deprecate --no-shell.
arm-unknown-linux-gnueabihf and aarch64-unknown-linux-gnu builds.--changes-only option to print what changes (for debugging purposes, not for consuming).--shell=SHELL and deprecate --no-shell.--shell=powershell), which solves #80. On Windows, powershell will become the CLI default in v2.0, and is the new default right now in the library.--kill from the man page, help, and completion. It will be removed in v2.0.Args is renamed to Config and the old name deprecated.get_args is deprecated in the view to be removed at some point (and only exist in the CLI).restart and watch_when_idle are deprecated and replaced with on_busy_update which clarifies the behaviour when receiving updates while a command is running.--on-busy-update= option to expose that builder option.--watch-when-idle (ref #123) in favour of --on-busy-update=do-nothing.fdb0cfb Soft-deprecate (in documentation only) Args.debug as it's not used any more.
Args.debug as it's not used any more.-w can be used to watch files as well as folders.- #157 Error and exit gracefully when the subprocess's environment would be too large (as a result of too many changes being added to the WATCHEXEC_*
WATCHEXEC_* environment variables instead of throwing a cryptic message ("Argument list too long")--no-environment to disable the WATCHEXEC_* variables being set, to avoid the above situation completely.--no-meta to disable only "metadata" events from being reported as above, which mitigates the above situation.watchexec = "=1.14.0".passcod/cargo-watch#149: if watched directory didn't contain a .git folder, thread would block (infinite loop)
Deps: notify (patch), globset (patch), clap (patch), nix (major: 0.15 → 0.17)
notify (patch), globset (patch), clap (patch), nix (major: 0.15 → 0.17)- #142: Change ignore globbing to behave as the readme documents: -i foo now matches the foo folder and descendants, instead of having to specify -i f
-i foo now matches the foo folder and descendants, instead of having to specify -i foo/**--watch-when-idle option that ignores events emitted while the command is running. This may help ignore changes made by the command itself (#40), though it of course also ignores all other changes during that time.Revert a change that made a type borrowed instead of the more sane (and more flexible) owned
zsh completions in tree and releases
.ignore files (#127)Args (#135)Handler trait (#133)--locked for reproducibility (#131)The man page was brought up-to-date to new options and a hint to use --
-- (#125)Always canonicalise paths, fixing a bug where some ignores would sometimes fail to apply
One column per quarter.