PM2 Commands

Start Processes

More than a couple of flags belongs in an ecosystem file rather than your shell history; the PM2 ecosystem generator writes one from a form.

List and Status

The restart counter (↺ in the list) climbing on its own means the app is crash-looping; read the error log before anything else.

Logs

PM2 captures each process's stdout and stderr to files under ~/.pm2/logs/.

PM2 does not rotate logs on its own, and a chatty app fills a disk quietly. Install pm2-logrotate on every server the first time you set one up.

Restart, Reload and Stop

stop keeps the entry (status stopped); delete forgets it. After any change you want back after a reboot, run pm2 save again.

Cluster Mode

Cluster mode runs several instances of the same Node app behind PM2's built-in load balancer, one per core with max. The app needs no code changes as long as it does not keep local state.

Cluster mode is Node-only, since it uses the Node cluster module. Sticky sessions and anything held in process memory (in-memory sessions, local caches) break across instances; move that state to Redis or the database first.

Save, Startup and Resurrect

Surviving a reboot is a two-step dance, and skipping the second step is the classic mistake.

So the full sequence is: pm2 startup, run the command it printed, get your apps running the way you want, then pm2 save. The hook restores whatever the last pm2 save captured, so rerun it after adding, deleting or renaming processes.

Windows

pm2 startup only knows Linux and macOS init systems. On Windows it prints nothing useful, so PM2 has to be installed as a Windows service instead.

The other option is pm2-installer, which registers PM2 itself as a Windows service so it starts before anyone logs in. Either way pm2 save is still what decides which apps come back. Everything else (list, logs, restart, monit, ecosystem files) behaves the same; paths in an ecosystem file want forward slashes or escaped backslashes.

Environment Variables

PM2 snapshots the environment when a process first starts and reuses it on every restart. Changing a variable in the shell or in .bashrc does nothing until you restart with --update-env or delete and start fresh. This surprises everyone once.

Node Version and Interpreter

The PM2 daemon keeps the Node version it was started with. Switching versions with nvm changes your shell, not the daemon, so apps keep running on the old binary until you reload the daemon.

In an ecosystem file the same settings are the interpreter and interpreter_args fields, which is the sane place to pin a version per app:

{
  name: "api",
  script: "./server.js",
  interpreter: "/home/deploy/.nvm/versions/node/v22.11.0/bin/node",
}

After an nvm upgrade, pm2 update is only half the job: the boot hook installed by pm2 startup has the old PATH written into it, so run pm2 unstartup, pm2 startup, the command it prints, then pm2 save again. PM2 no longer bundles ts-node, so TypeScript needs npm i -g ts-node typescript (or a local install plus npx); compiling to JavaScript first and running the output is steadier in production.

Ecosystem File

ecosystem.config.js holds everything the start flags express, in a file you can commit. pm2 init writes a sample, or the PM2 ecosystem generator builds one from a form.

module.exports = {
  apps: [{
    name: "api",
    script: "./server.js",
    instances: "max",
    exec_mode: "cluster",
    max_memory_restart: "300M",
    args: "--port 3000",
    env: { NODE_ENV: "development" },
    env_production: { NODE_ENV: "production" },
  }],
};

Monitoring

pm2 monit is the fastest answer to "which process is eating the CPU". For alerting and history, PM2's hosted monitoring (pm2 plus) exists, but plain pm2 monit over SSH covers day-to-day checks.

Install and Upgrade

Upgrading the npm package alone changes nothing for running apps, since the old daemon stays in memory. pm2 update is what swaps it. Under nvm, PM2 is installed per Node version, so a new Node version means installing PM2 again.

Deployment

pm2 deploy reads a deploy section in the ecosystem file (host, repo, path, post-deploy command) and works fine for simple git-based deploys. Teams that outgrow it usually move to CI plus pm2 reload over SSH.

If you would rather have the init system own the process, with proper dependencies and journald logging, the pm2 to systemd converter turns an ecosystem file into unit files, and the systemctl cheat sheet covers managing them.

Gotchas

• pm2 startup alone does nothing at boot. It prints a command; run that command, then pm2 save. The saved dump is what gets restored, so save again after every change to the list.
• pm2 reload is only zero-downtime in cluster mode with two or more instances. In fork mode it is just a restart with a friendlier name.
• Restarts keep the environment from the first start. New or changed variables need pm2 restart api --update-env, or a delete and a fresh start.
• Logs are never rotated by default. pm2 install pm2-logrotate before the disk fills, and pm2 flush when it already has.
• --watch in production causes restart loops when the app writes into its own directory (logs, uploads). Use --ignore-watch, or better, no watch at all outside development.
• pm2: command not found in cron, CI or GitHub Actions usually means npm's global bin is not on that context's PATH; use the absolute path to the binary.
• Switching Node with nvm does not move the apps. The daemon holds the old version until pm2 update, and the boot hook holds the old PATH until you rerun pm2 startup and pm2 save.
• pm2 kill takes down the daemon and every app with it. To remove one app, pm2 delete api.