pm2 Documentation

File: README.md Copy Chapter

PM2 is a production process manager for Node.js/Bun applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime and to facilitate common system admin tasks.

Starting an application in production mode is as easy as:

$ pm2 start app.js

PM2 is battle-tested by a comprehensive test suite.

Official website: https://pm2.keymetrics.io/

Works on Linux, macOS, and Windows. Supports Node.js 18+ and Bun 1+.

Installing PM2 Copy Chapter

With NPM Copy Section

$ npm install pm2 -g

With Bun Copy Section

$ bun install pm2 -g

If you only have Bun installed (no Node.js), symlink node to bun so PM2's #!/usr/bin/env node shebang resolves to Bun's node-compatibility runtime:

$ sudo ln -s $(which bun) /usr/local/bin/node

You can install Node.js easily with NVM or FNM or install Bun with curl -fsSL https://bun.sh/install | bash

Start an application Copy Section

You can start any application (Node.js, Bun, and also Python, Ruby, binaries in $PATH...) like that:

$ pm2 start app.js

Your app is now daemonized, monitored and kept alive forever.

Managing Applications Copy Section

Once applications are started you can manage them easily:

To list all running applications:

$ pm2 list

Managing apps is straightforward:

$ pm2 stop     <app_name|namespace|id|'all'|json_conf>
$ pm2 restart  <app_name|namespace|id|'all'|json_conf>
$ pm2 delete   <app_name|namespace|id|'all'|json_conf>

To have more details on a specific application:

$ pm2 describe

To monitor logs, custom metrics, application information:

$ pm2 monit

More about Process Management

Cluster Mode: Node.js Load Balancing & Zero Downtime Reload Copy Section

Cluster mode starts multiple Node.js processes and load-balances HTTP/TCP/UDP queries between them. This significantly increases throughput on multi-core machines and improves reliability (faster socket re-balancing in case of unhandled errors).

Starting a Node.js application in cluster mode that will leverage all CPUs available:

$ pm2 start api.js -i

`` can be 'max', -1 (all cpu minus 1) or a specified number of instances to start.

Zero Downtime Reload

Hot Reload allows you to update an application without any downtime:

$ pm2 reload all

More information about how PM2 makes clustering easy

Container Support Copy Section

With the drop-in replacement command for node, called pm2-runtime, run your Node.js application in a hardened production environment.
Using it is seamless:

RUN npm install pm2 -g
CMD [ "pm2-runtime", "npm", "--", "start" ]

Read More about the dedicated integration

Terminal Based Monitoring Copy Section

Monitor all processes launched straight from the command line:

$ pm2 monit

Log Management Copy Section

To consult logs just type the command:

$ pm2 logs

Standard, Raw, JSON and formatted output are available.

Examples:

$ pm2 logs APP-NAME       # Display APP-NAME logs
$ pm2 logs --json         # JSON output
$ pm2 logs --format       # Formatted output

$ pm2 flush               # Flush all logs
$ pm2 reloadLogs          # Reload all logs

To enable log rotation install the following module

$ pm2 install pm2-logrotate

More about log management

Startup Scripts Generation Copy Section

PM2 can generate and configure a Startup Script to keep PM2 and your processes alive at every server restart.

Init Systems Supported: systemd, upstart, systemv, openrc, launchd, rcd, rcd-openbsd, smf

# Generate Startup Script
$ pm2 startup

# Freeze your process list across server restart
$ pm2 save

# Remove Startup Script
$ pm2 unstartup

More about Startup Scripts Generation

Updating PM2 Copy Section

# Install latest PM2 version
$ npm install pm2@latest -g
# Save process list, exit old PM2 & restore all processes
$ pm2 update

PM2 updates are seamless

PM2+ Monitoring Copy Chapter

If you manage your apps with PM2, PM2+ makes it easy to monitor and manage apps across servers.

Feel free to try it:

Discover the monitoring dashboard for PM2

Thanks in advance and we hope that you like PM2!

CHANGELOG Copy Chapter

CHANGELOG

Contributors Copy Chapter

Contributors

License Copy Chapter

PM2 is made available under the terms of the GNU Affero General Public License 3.0 (AGPL 3.0).
For other licenses contact us.

File: examples/using-pm2-and-transpilers/README.md Copy Chapter

Coffee Script Copy Chapter

$ pm2 install coffee-script
$ pm2 start echo.coffee

Typescript Copy Chapter

$ pm2 install typescript
$ pm2 start http.ts

Livescript Copy Chapter

$ pm2 install livescript
$ pm2 start echo.ls

File: examples/test-all-keymetrics-features/README.md Copy Chapter

Try all features of Keymetrics:

# Make sure you've created keymetrics account
$ pm2 register
# Start all applications
$ pm2 start process.config.js
# Open Dashboard
$ pm2 open

File: examples/sourcemap-auto-resolve/README.md Copy Chapter

Here is a source map support demo.
Source map are automatically handled by pm2:

$ pm2 start process.config.js

Here is the result:

PM2        | App [API-minified] with id [1] and pid [10634], exited with code [1] via signal [SIGINT]
PM2        | Starting execution sequence in -fork mode- for app name:API-minified id:1
PM2        | App name:API-minified id:1 online
1|API-mini | Error: muhahahaha
1|API-mini |     at Object.<anonymous> (/home/unitech/keymetrics/pm2/examples/sourcemap-auto-resolve/API.js:226:7)
1|API-mini |     at Module._compile (module.js:641:30)
1|API-mini |     at Object.Module._extensions..js (module.js:652:10)
1|API-mini |     at Module.load (module.js:560:32)
1|API-mini |     at tryModuleLoad (module.js:503:12)
1|API-mini |     at Function.Module._load (module.js:495:3)
1|API-mini |     at Function._load (/home/unitech/keymetrics/pm2/node_modules/pmx/lib/transaction.js:94:21)
1|API-mini |     at Object.<anonymous> (/home/unitech/keymetrics/pm2/lib/ProcessContainerFork.js:80:21)
1|API-mini |     at Module._compile (module.js:641:30)
1|API-mini |     at Object.Module._extensions..js (module.js:652:10)
PM2        | App [API-minified] with id [1] and pid [10660], exited with code [1] via signal [SIGINT]
PM2        | Starting execution sequence in -fork mode- for app name:API-minified id:1

You will see that the line has been resolved:

1|API-mini | Error: muhahahaha
1|API-mini |     at Object.<anonymous> (/home/unitech/keymetrics/pm2/examples/sourcemap-auto-resolve/API.js:226:7)
1|API-mini |     at Module._compile (module.js:641:30)

File: examples/module-test/README.md Copy Chapter

This is a sample module that have been generate via pm2 module:generate:

>>> pm2 module:generate
[PM2] Spawning PM2 daemon with pm2_home=/home/unitech/.pm2
[PM2] PM2 Successfully daemonized
[PM2][Module] Module name: module-test
[PM2][Module] Getting sample app
Cloning into 'module-test'...

npm notice created a lockfile as package-lock.json. You should commit this file.
added 4 packages in 0.939s

[PM2][Module] Module sample created in folder:  /home/unitech/keymetrics/pm2/examples/module-test

Start module in development mode:
$ cd module-test/
$ pm2 install .

Module Log:
$ pm2 logs module-test

Uninstall module:
$ pm2 uninstall module-test

Force restart:
$ pm2 restart module-test

Configuration Copy Chapter

To add configuration to the module:

$ pm2 set module-test:var1 value1

You will then be able to access to this value via

pmx.initModule({
}, function(err, conf) {
  // var1 = value1
  console.log(conf.var1);
});

File: examples/ecosystem-file/README.md Copy Chapter

Here we have 3 applications (apps folder) that we can start with process file.
These process file can be of different format, javascript, json or yaml:

.
├── apps
│   ├── connection_check.sh
│   ├── http.js
│   └── worker.js
├── process.config.js
├── process.json
└── process.yml

To start them:

$ pm2 start process.config.js
$ pm2 delete all
$ pm2 start process.json
$ pm2 delete all
$ pm2 start process.yml

File: examples/cluster-tcp/README.md Copy Chapter

To start tcp application in cluster mode:

$ pm2 start ecosystem.config.js
# OR
$ pm2 start tcp.js -i max