README

P(rocess) M(anager) 2
  Runtime Edition




  



  



   








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:

bash
$ 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

 With NPM

bash
$ npm install pm2 -g


 With Bun

bash
$ 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:

bash
$ 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

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

bash
$ pm2 start app.js
$ pm2 start app.ts
$ pm2 start app.py


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

 Managing Applications

Once applications are started you can manage them easily:

!Process listing

To list all running applications:

bash
$ pm2 list


Managing apps is straightforward:

bash
$ pm2 stop     
$ pm2 restart  
$ pm2 delete   


To have more details on a specific application:

bash
$ pm2 describe 


To monitor logs, custom metrics, application information:

bash
$ pm2 monit


More about Process Management

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

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).

!Framework supported

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

bash
$ 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:

bash
$ pm2 reload all


More information about how PM2 makes clustering easy

 Container Support

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:

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


Read More about the dedicated integration

 Terminal Based Monitoring

!Monit

Monitor all processes launched straight from the command line:

bash
$ pm2 monit


 Log Management

To consult logs just type the command:

bash
$ pm2 logs


Standard, Raw, JSON and formatted output are available.

Examples:

bash
$ pm2 logs APP-NAME        Display APP-NAME logs
$ pm2 logs --json          JSON output
$ pm2 logs 

Top issues

Latest release

7.1.2

 Bug Fixes

- pm2 update under a pm2 startup systemd unit no longer gets its new daemon and apps killed by ExecStop=pm2 kill (systemd = 232) 5000
- filter_env: true works again (ignored since 4.4.1): apps only inherit PATH, HOME, USER, locales and a few OS variables besides their env 6176
- filter_env also applies to --update-env restart/reload and to cluster workers; --filter-env alone means true 6176
- pm2.disconnect() no longer throws nor calls back twice when a socket takes more than 200ms to close
- pm2 start --container uses keymetrics/pm2:-trixie (was the 2018 latest image, and -