PM2 Cheatsheet - Node.js Process Manager Reference
Running node app.js in the foreground means watching a process die or a memory leak build with no safety net. PM2 layers on daemon supervision, self-restart, cluster mode, logging and boot-start as one loop. This table is grouped into start/run, logs, monitoring, cluster, startup and ecosystem.config.js, with deployment-critical flags, and it calls out CLI differences like reload vs restart and the pm2 save + startup pair for crash recovery. After reading you can set up supervision, scaling and self-healing for a Node service on your own.
Start & Stop 12
pm2 start app.jspm2 start app.js --name "api"pm2 start app.js -i maxpm2 start app.js -i 4pm2 start ecosystem.config.jspm2 stop allpm2 stop apipm2 restart apipm2 reload apipm2 delete apipm2 start app.js --watchpm2 killLogs 5
pm2 logspm2 logs api --lines 100pm2 logs api --errpm2 flushpm2 install pm2-logrotateMonitor & Status 6
pm2 listpm2 show apipm2 monitpm2 statuspm2 describe apipm2 jlistStartup 4
pm2 startuppm2 savepm2 resurrectpm2 unstartupCluster & Scale 5
pm2 scale api +2pm2 scale api 8pm2 reset apipm2 serve ./dist 8080pm2 deploy ecosystem.config.js productionecosystem.config.js 6
module.exports = { apps: [{ name: "api", script: "app.js", instances: "max", exec_mode: "cluster" }] }env: { NODE_ENV: "production", PORT: 3000 }max_memory_restart: "1G"error_file: "./logs/err.log", out_file: "./logs/out.log"watch: true, ignore_watch: ["node_modules", "logs"]pm2 start ecosystem.config.js --env productionTypical Use Case
Before a Node service goes live, start it with -i max to spawn one process per CPU core, then centralize tuning in ecosystem.config.js; when a process crashes or leaks memory, watch trends with pm2 monit and set max_memory_restart to auto-restart over-limit processes; to release without dropping online users use reload for zero-downtime restarts, especially for stateful or long-lived services; to bring everything back after a reboot combine pm2 save with pm2 startup; for daily triage run pm2 list to find non-online processes, then pm2 logs for stack traces.
Command Examples
Start in cluster mode and confirm it is running
pm2 start app.js -i max
pm2 list-i max 按 CPU 核数启动；pm2 list 看 status 是否 online、instances 是否等于核数，restart:0 表示未发生过崩溃重启。
Output
│ api │ online │ 8 │ 4.2MB │ restart:0 │
Zero-downtime rolling reload after a config change
pm2 reload api集群模式下 reload 会逐个重启进程实现零停机；若应用为 fork（单进程）模式，reload 与 restart 效果相同、无法零停机。
Enable log rotation to avoid filling the disk
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M日志无限增长会撑爆磁盘；安装后调整 max_size（默认 10M）与默认每天轮转，旧日志按保留策略清除。
Output
Modifying value of setting [pm2-logrotate:max_size] with value 10M
Common Pitfalls
- pm2 kill exits the daemon and clears processes — never use kill to "restart PM2" in production; restart the app or the host instead.
- pm2 startup only prints a command; you must actually run that sudo/root line once for boot-start to take effect — a step many people skip.
- reload is zero-downtime only in cluster mode; in fork mode it behaves like restart and drops connections.
- --watch can treat node_modules or logs as restart triggers; always set ignore_watch to avoid useless restart churn.
- pm2 monit is a live panel that stops sampling when you exit; for sustained memory/restart trends use monitoring/alerting rather than watching a terminal.
Tips
- reload is smoother than restart; in cluster mode it restarts one by one (zero downtime); in fork mode reload == restart.
- pm2 save + pm2 startup restores all processes after a reboot.
- For leaks: watch pm2 monit; set max_memory_restart as a safety net.
FAQ
What is the difference between pm2 reload and restart?
restart kills the process and starts it again with a brief downtime; reload in cluster mode cycles workers one by one for zero-downtime updates. Use pm2 reload app for smooth deploys with cluster mode, and restart when you just want to reset a single instance.
pm2 keeps failing with port already in use after restarts — what do I do?
Usually an old process was not fully cleaned up or the port is held elsewhere. Run pm2 delete app to remove the old instance, inspect the port (ss -tlnp on Linux) and kill the holder, verify PORT is free, then pm2 start again. A crash-restart loop can look the same — check pm2 logs for the real exception.
How do I configure pm2 to start on system boot?
Start the apps to persist with pm2 start, run pm2 save to store the list, then run pm2 startup and execute the init command it prints (it generates a systemd or sysv unit). On the next boot PM2 restores the saved apps automatically.
Does pm2 auto-restart crashed processes, and how do I cap memory usage?
A normal crash is restarted by default; set max_restarts to bound repeated retries. To stop a memory leak from exhausting RAM, set --max-memory-restart 1G on start or max_memory_restart in ecosystem.config.js so pm2 restarts above the threshold. Pair it with log rotation for long-lived heavy instances.
What does pm2 save do, and what happens if I skip it?
pm2 save writes the current process list into a dump file, which is required for pm2 startup (boot persistence) and for pm2 resurrect to restore apps. Without it, a reboot or fresh machine loses the managed list and you must pm2 start everything again manually.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Jul 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us