nodemon

nodemon is a tool that helps develop Node.js based applications by automatically restarting the node application when file changes in the directory are detected.

nodemon does not require any additional changes to your code or method of development. nodemon is a replacement wrapper for node. To use nodemon, replace the word node on the command line when executing your script.

Installation

Either through cloning with git or by using npm (the recommended way):

npm install -g nodemon # or using yarn: yarn global add nodemon

And nodemon will be installed globally to your system path.

You can also install nodemon as a development dependency:

npm install --save-dev nodemon # or using yarn: yarn add nodemon -D

With a local installation, nodemon will not be available in your system path, so you can't use it directly from the command line. Instead, the local installation of nodemon can be run by calling it from within an npm script (such as npm start) or using npx nodemon.

Usage

nodemon wraps your application, so you can pass all the arguments you would normally pass to your app:

nodemon [your node app]

For CLI options, use the -h (or --help) argument:

nodemon -h

Using nodemon is simple, if my application accepted a host and port as the arguments, I would start it like so:

nodemon ./server.js localhost 8080

Any output from this script is prefixed with [nodemon], otherwise all output from your application, errors included, will be echoed out as expected.

You can also pass the inspect flag to node through the command line as you would normally:

nodemon --inspect ./server.js 80

If you have a package.json file for your app, you can omit the main script entirely and nodemon will read the package.json for the main property and use that value as the app (ref).

nodemon will also search for the scripts.start property in package.json (as of nodemon 1.1.x).

Also check out the FAQ or issues for nodemon.

Automatic re-running

nodemon was originally written to restart hanging processes such as web servers, but now supports apps that cleanly exit. If your script exits cleanly, nodemon will continue to monitor the directory (or directories) and restart the script if there are any changes.

Kill timeout (force SIGKILL)

By default, when nodemon restarts or stops your app it sends the configured signal (default SIGUSR2) and waits for the process to exit. If the app ignores that signal, the restart can hang.

Use --kill-timeout <ms> so nodemon force-kills with SIGKILL only if the process is still alive after the timeout. If it exits in time, no force kill runs. Off by default — without the flag, behavior is unchanged.

# force-kill if still running 3s after the graceful signal
nodemon --kill-timeout 3000 server.js

# suffixes also work
nodemon --kill-timeout 500ms server.js
nodemon --kill-timeout 2s server.js

{
  "killTimeout": 3000
}

Bare numbers are milliseconds (unlike --delay, which is seconds unless you use ms).

Manual restarting

Whilst nodemon is running, if you need to manually restart your application, instead of stopping and restarting nodemon, you can type rs with a carriage return, and nodemon will restart your process.

You can also pass one-shot extra arguments for a single run:

# while nodemon is running, type:
rs --debug
rs --port 4000 --env staging
rs --name "my app"

Those extra args are appended to the original command for that restart only. After that one run, the next plain rs, nodemon.restart(), or (once the one-shot run has started) file-change restart uses the original command again.

Input	Effect
`rs`	Restart with the original command (same as always); cancels a pending one-shot
`rs <args>`	Restart once with `<args>` appended; then back to original
other stdin	Still forwarded to the child process (unchanged)

Safety: one-shot args must not contain shell metacharacters (;, |, &, $, backticks, redirects, etc.). Unsafe args are refused and nodemon does not restart with them (avoids accidental shell injection on the spawn path).

Programmatically, the same one-shot behaviour is available via:

nodemon.restart({ args: ['--port', '4000'] }); // one run only
nodemon.restart(); // original command (clears any pending one-shot)

Config files

nodemon supports local and global configuration files. These are usually named nodemon.json and can be located in the current working directory or in your home directory. An alternative local configuration file can be specified with the --config <file> option.

The specificity is as follows, so that a command line argument will always override the config file settings:

command line arguments
local config
global config

A config file can take any of the command line arguments as JSON key values, for example:

{
  "verbose": true,
  "ignore": ["*.test.js", "**/fixtures/**"],
  "execMap": {
    "rb": "ruby",
    "pde": "processing --sketch={{pwd}} --run"
  }
}

The above nodemon.json file might be my global config so that I have support for ruby files and processing files, and I can run nodemon demo.pde and nodemon will automatically know how to run the script even though there is no out-of-the-box support for processing scripts.

A further example of options can be seen in sample-nodemon.md

package.json

If you want to keep all your package configurations in one place, nodemon supports using package.json for configuration. Specify the config in the same format as you would for a config file but under nodemonConfig in the package.json file, for example, take the following package.json:

{
  "name": "nodemon",
  "homepage": "http://nodemon.io",
  "...": "... other standard package.json values",
  "nodemonConfig": {
    "ignore": ["**/test/**", "**/docs/**"],
    "delay": 2500
  }
}

Note that if you specify a --config file or provide a local nodemon.json any package.json config is ignored.

This section needs better documentation, but for now you can also see nodemon --help config (also here).

Using nodemon as a module

Please see doc/requireable.md

Using nodemon as child process

Please see doc/events.md

Running non-node scripts

nodemon can also be used to execute and monitor other programs. nodemon will read the file extension of the script being run and monitor that extension instead of .js if there's no nodemon.json:

nodemon --exec "python -v" ./app.py

Now nodemon will run app.py with python in verbose mode (note that if you're not passing args to the exec program, you don't need the quotes), and look for new or modified files with the .py extension.

Default executables

Using the nodemon.json config file, you can define your own default executables using the execMap property. This is particularly useful if you're working with a language that isn't supported by default by nodemon.

To add support for nodemon to know about the .pl extension (for Perl), the nodemon.json file would add:

{
  "execMap": {
    "pl": "perl"
  }
}

Now running the following, nodemon will know to use perl as the executable:

nodemon script.pl

It's generally recommended to use the global nodemon.json to add your own execMap options. However, if there's a common default that's missing, this can be merged into the project so that nodemon supports it by default, by changing default.js and sending a pull request.

Monitoring multiple directories

By default nodemon monitors the current working directory. If you want to take control of that option, use the --watch option to add specific paths:

nodemon --watch app --watch libs app/server.js

Now nodemon will only restart if there are changes in the ./app or ./libs directory. By default nodemon will traverse sub-directories, so there's no need to explicitly include sub-directories.

Nodemon also supports unix globbing, e.g --watch './lib/*'. The globbing pattern must be quoted. For advanced globbing, see picomatch documentation, the library that nodemon uses through chokidar (which in turn uses it through anymatch).

Specifying extension watch list

By default, nodemon looks for files with the .js, .mjs, .coffee, .litcoffee, and .json extensions. If you use the --exec option and monitor app.py nodemon will monitor files with the extension of .py. However, you can specify your own list with the -e (or --ext) switch like so:

nodemon -e js,pug

Now nodemon will restart on any changes to files in the directory (or subdirectories) with the extensions .js, .pug.

Ignoring files

By default, nodemon will only restart when a .js JavaScript file changes. In some cases you will want to ignore some specific files, directories or file patterns, to prevent nodemon from prematurely restarting your application.

This can be done via the command line:

nodemon --ignore lib/ --ignore tests/

Or specific files can be ignored:

nodemon --ignore lib/app.js

Patterns can also be ignored (but be sure to quote the arguments):

nodemon --ignore 'lib/*.js'

Important the ignore rules are patterns matched to the full absolute path, and this determines how many files are monitored. If using a wild card glob pattern, it needs to be used as ** or omitted entirely. For example, nodemon --ignore '**/test/**' will work, whereas --ignore '*/test/*' will not.

Note that by default, nodemon will ignore the .git, node_modules, bower_components, .nyc_output, coverage and .sass-cache directories and add your ignored patterns to the list. If you want to indeed watch a directory like node_modules, you need to override the underlying default ignore rules.

Application isn't restarting

In some networked environments (such as a container running nodemon reading across a mounted drive), you will need to use the legacyWatch: true which enables Chokidar's polling.

Via the CLI, use either --legacy-watch or -L for short:

nodemon -L

Though this should be a last resort as it will poll every file it can find.

Delaying restarting

In some situations, you may want to wait until a number of files have changed. The timeout before checking for new file changes is 1 second. If you're uploading a number of files and it's taking some number of seconds, this could cause your app to restart multiple times unnecessarily.

To add an extra throttle, or delay restarting, use the --delay command:

nodemon --delay 10 server.js

For more precision, milliseconds can be specified. Either as a float:

nodemon --delay 2.5 server.js

Or using the time specifier (ms):

nodemon --delay 2500ms server.js

The delay figure is number of seconds (or milliseconds, if specified) to delay before restarting. So nodemon will only restart your app the given number of seconds after the last file change.

If you are setting this value in nodemon.json, the value will always be interpreted in milliseconds. E.g., the following are equivalent:

nodemon --delay 2.5

{
  "delay": 2500
}

Ignoring changes right after startup

Some applications write generated files (caches, compiled assets, lock files, etc.) as soon as they start. Nodemon can see those writes and restart the process immediately, which can create a restart loop.

Use --startUpWatchDelay (or startUpWatchDelay in config) to ignore file changes for a short period after the child process starts. Once that window ends, normal watching resumes. This is not the same as --delay, which waits after a file change before restarting.

# ignore changes for 2 seconds after each start
nodemon --startUpWatchDelay 2 server.js

# or with an explicit milliseconds specifier
nodemon --startUpWatchDelay 2000ms server.js

In nodemon.json / package.json nodemonConfig, the value is always milliseconds:

{
  "startUpWatchDelay": 2000
}

You can combine both options when needed: startUpWatchDelay suppresses the restart loop on boot; delay still debounces restarts from later edits.

Restart loop guard

If something keeps changing watched files (or your app keeps writing to them), nodemon can restart in a tight loop. Enable restartLoopGuard so that when too many automatic file-change restarts happen within a short time window, nodemon pauses further automatic restarts and prints a clear warning instead of looping forever.

This is off by default. When unset or false, restart behavior is unchanged. Manual restart (rs or the configured restartable command / signal) is not blocked.

CLI (optional value; defaults are 10 restarts in 10 seconds):

# enable with defaults (10 restarts / 10s)
nodemon --restartLoopGuard server.js

# max 5 restarts in the default 10s window
nodemon --restartLoopGuard 5 server.js

# max 10 restarts within 5 seconds
nodemon --restartLoopGuard 10/5s server.js

# same with an explicit milliseconds window
nodemon --restartLoopGuard 10/5000ms server.js

Config (nodemon.json / nodemonConfig):

{
  "restartLoopGuard": true
}

{
  "restartLoopGuard": {
    "max": 10,
    "window": 10000
  }
}

window in config is always milliseconds. After the window slides past older restarts, automatic restarts are allowed again; or type rs to force a restart while paused.

Restart reason

Nodemon can tell you why it restarted. The restart event always receives an optional second argument (existing listeners that only use files keep working):

`reason.type`	Meaning
`watch`	A watched file changed (`reason.files` lists paths)
`manual`	User typed the restartable command (default `rs`)
`api`	`nodemon.restart()` / programmatic restart
`signal`	Process signal used to request a restart

When restarting with one-shot extra args (rs <args> or nodemon.restart({ args })), reason.args is the string array of those args.

require('nodemon')({ script: 'server.js' }).on('restart', function (files, reason) {
  console.log('restart type:', reason && reason.type);
  if (files) console.log('files:', files);
});

By default the reason is only written to detail logs (--verbose). To always print it at status level:

nodemon --restartReason server.js

{
  "restartReason": true
}

restartReason only affects logging / event metadata. It does not change whether a restart happens.

Filtering which file events restart the app (`restartOn`)

By default nodemon restarts on change, add, and unlink (delete) events — same as always. Use restartOn to limit which filesystem events trigger a restart.

Value	Restarts on
`all` (default)	change, add, and unlink
`change`	modifications only
`add`	new files only (after the initial watch is ready)
`unlink`	deletions only
`change,add`	combination (comma-separated or array in config)

Unset / all keeps full backward compatibility with previous nodemon behavior. Manual restart (rs) is not affected.

CLI

nodemon --restartOn change server.js
nodemon --restartOn add server.js
nodemon --restartOn change,add server.js

Config

{
  "restartOn": "change"
}

{
  "restartOn": ["change", "add"]
}

restartOn and restartReason are independent: you can filter which events restart the process and still receive (or log) why a restart occurred.

MCP server mode (agent inspection & control)

Nodemon can expose an opt-in MCP (Model Context Protocol) surface so an agent (or plain HTTP/curl) can inspect runtime status, watched files, restart history, last crash, config, and logs, and can restart or quit nodemon safely.

Off by default. If you do not pass --mcp / set "mcp": true, behavior is unchanged and MCP is not started.

Security defaults (prod-oriented):

Binds 127.0.0.1 only by default (no open network control plane)
No Access-Control-Allow-Origin: * (avoids browser CSRF to localhost)
Optional --mcpToken — when set, required on all routes except GET /health
Non-loopback bind (--mcpHost 0.0.0.0) is refused unless you pass --mcpAllowRemote and --mcpToken
JSON bodies capped at 1MB; server stops cleanly on quit/reset (no port leak)
Full MCP SSE/stdio needs optional package @modelcontextprotocol/sdk (Node >= 18); REST works without it

Practical note: For hands-on testing, use REST /api/*. See also doc/mcp.md.

1) Start nodemon with MCP (HTTP)

# from the nodemon repo checkout:
node ./bin/nodemon.js --mcp --mcpPort 8765 --ext js test/fixtures/app.js

# with token (recommended on shared machines):
node ./bin/nodemon.js --mcp --mcpToken secret --mcpPort 8765 server.js

# if nodemon is installed globally / via npx:
nodemon --mcp --mcpPort 8765 server.js

If the port is busy, pick another: --mcpPort 8877.

2) REST API (recommended for testing — no MCP client)

Base URL: http://127.0.0.1:8765 (or your --mcpPort).

Method	Path	Purpose
GET	`/health`	Liveness + tool name list (no auth)
GET	`/api/status`	Runtime status + config summary
GET	`/api/config`	Config summary only
GET	`/api/watched?limit=50`	Watched files (tracks add/unlink)
GET	`/api/history`	Restart history
GET	`/api/logs?limit=50`	Recent nodemon logs (`?type=status` optional)
GET	`/api/tools`	List MCP tool names/descriptions
POST	`/api/tools/<name>`	Invoke a tool (JSON body = arguments)
POST	`/api/restart`	Same as tool `nodemon_restart`
POST	`/api/quit`	Same as tool `nodemon_quit` (exits nodemon)

Example session (second terminal):

PORT=8765
BASE=http://127.0.0.1:$PORT
# TOKEN=secret   # if you started with --mcpToken

curl -s $BASE/health
curl -s ${TOKEN:+-H "Authorization: Bearer $TOKEN"} $BASE/api/status
curl -s ${TOKEN:+-H "Authorization: Bearer $TOKEN"} -X POST $BASE/api/tools/nodemon_status
curl -s ${TOKEN:+-H "Authorization: Bearer $TOKEN"} -X POST $BASE/api/tools/nodemon_restart

One-shot smoke script from the repo:

bash scripts/mcp-smoke.sh 8765

3) MCP tools (for agents)

Tool	Arguments	Effect
`nodemon_status`	—	Status snapshot (includes `lastCrash`, pids, config)
`nodemon_watched_files`	`limit?`	Watched files
`nodemon_restart_history`	`limit?`	Restart history (`trigger: mcp` for agent restarts)
`nodemon_last_crash`	—	Most recent crash details (`null` if none)
`nodemon_logs`	`limit?`, `type?`	Nodemon logs
`nodemon_config`	—	Config summary
`nodemon_restart`	—	Restart child (same as `rs` / API)
`nodemon_quit`	—	Quit nodemon (response sent before exit)

SSE MCP transport (optional; requires optional SDK): GET /mcp then POST /messages?sessionId=….

4) stdio MCP (client spawns nodemon)

node ./bin/nodemon.js --mcp-stdio --ext js test/fixtures/app.js

Caveat: stdio is owned by the MCP protocol — prefer HTTP --mcp while developing.

Config (`nodemon.json`)

{
  "mcp": true,
  "mcpPort": 8765,
  "mcpHost": "127.0.0.1",
  "mcpTransport": "http",
  "mcpToken": null,
  "mcpAllowRemote": false
}

Gracefully reloading your script

It is possible to have nodemon send any signal that you specify to your application.

nodemon --signal SIGHUP server.js

Your application can handle the signal as follows.

process.on("SIGHUP", function () {
  reloadSomeConfiguration();
  process.kill(process.pid, "SIGTERM");
})

Please note that nodemon will send this signal to every process in the process tree.

If you are using cluster, then each worker (as well as the master) will receive the signal. If you wish to terminate all workers on receiving a SIGHUP, a common pattern is to catch the SIGHUP in the master, and forward SIGTERM to all workers, while ensuring that all workers ignore SIGHUP.

if (cluster.isMaster) {
  process.on("SIGHUP", function () {
    for (const worker of Object.values(cluster.workers)) {
      worker.process.kill("SIGTERM");
    }
  });
} else {
  process.on("SIGHUP", function() {})
}

Controlling shutdown of your script

nodemon sends a kill signal to your application when it sees a file update. If you need to clean up on shutdown inside your script you can capture the kill signal and handle it yourself.

The following example will listen once for the SIGUSR2 signal (used by nodemon to restart), run the clean up process and then kill itself for nodemon to continue control:

// important to use `on` and not `once` as nodemon can re-send the kill signal
process.on('SIGUSR2', function () {
  gracefulShutdown(function () {
    process.kill(process.pid, 'SIGTERM');
  });
});

Note that the process.kill is only called once your shutdown jobs are complete. Hat tip to Benjie Gillam for writing this technique up.

Triggering events when nodemon state changes

If you want growl like notifications when nodemon restarts or to trigger an action when an event happens, then you can either require nodemon or add event actions to your nodemon.json file.

For example, to trigger a notification on a Mac when nodemon restarts, nodemon.json looks like this:

{
  "events": {
    "restart": "osascript -e 'display notification \"app restarted\" with title \"nodemon\"'"
  }
}

A full list of available events is listed on the event states wiki. Note that you can bind to both states and messages.

Pipe output to somewhere else

nodemon({
  script: ...,
  stdout: false // important: this tells nodemon not to output to console
}).on('readable', function() { // the `readable` event indicates that data is ready to pick up
  this.stdout.pipe(fs.createWriteStream('output.txt'));
  this.stderr.pipe(fs.createWriteStream('err.txt'));
});

Using nodemon in your gulp workflow

Check out the gulp-nodemon plugin to integrate nodemon with the rest of your project's gulp workflow.

Using nodemon in your Grunt workflow

Check out the grunt-nodemon plugin to integrate nodemon with the rest of your project's grunt workflow.

Pronunciation

nodemon, is it pronounced: node-mon, no-demon or node-e-mon (like pokémon)?

Well...I've been asked this many times before. I like that I've been asked this before. There's been bets as to which one it actually is.

The answer is simple, but possibly frustrating. I'm not saying (how I pronounce it). It's up to you to call it as you like. All answers are correct :)

Design principles

Fewer flags is better
Works across all platforms
Fewer features
Let individuals build on top of nodemon
Offer all CLI functionality as an API
Contributions must have and pass tests

Nodemon is not perfect, and CLI arguments have sprawled beyond where I'm completely happy, but perhaps they can be reduced a little one day.

FAQ

See the FAQ and please add your own questions if you think they would help others.

Backers

Thank you to all our backers! 🙏

License

MIT http://rem.mit-license.org

Name		Name	Last commit message	Last commit date
Latest commit History 1,496 Commits
.github		.github
bin		bin
doc		doc
lib		lib
scripts		scripts
test		test
website		website
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.jshintrc		.jshintrc
.npmignore		.npmignore
.npmrc		.npmrc
.prettierrc.json		.prettierrc.json
.releaserc		.releaserc
.travis.yml		.travis.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
commitlint.config.js		commitlint.config.js
faq.md		faq.md
index.d.ts		index.d.ts
jsconfig.json		jsconfig.json
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation