sodcalculator

10 Tech How-To

PM2 Setup on Linux: Install, Configure, Run

Guide 10-46563 · Updated · Step by step

PM2 is a production-grade process manager for Node.js applications that keeps your apps running continuously, restarts them after crashes, and manages logs and startup on boot. This guide walks you through installing PM2 on a Linux server, setting up your first application, and configuring it to start automatically when the server reboots.

What You’ll Need

  • A Linux server (Ubuntu, Debian, CentOS, or similar) with sudo or root access
  • Node.js and npm installed (PM2 is installed via npm)
  • An existing Node.js application to manage (or you can create a test app)
  • Basic familiarity with the command line

Step-by-Step

  1. Update your package lists. Run sudo apt update (on Debian/Ubuntu) or sudo yum update (on CentOS/RHEL) to ensure your system has the latest package information.
  2. Install Node.js and npm if not already installed. On Ubuntu/Debian, you can use sudo apt install nodejs npm. On CentOS/RHEL, use sudo yum install nodejs npm. Verify with node -v and npm -v.
  3. Install PM2 globally using npm. Run sudo npm install -g pm2. This installs the PM2 command-line tool system-wide.
  4. Verify the installation. Check the version with pm2 --version. You should see a version number like 5.3.0 or newer.
  5. Navigate to your application directory. Use cd /path/to/your/app to move into the folder containing your Node.js application.
  6. Start your application with PM2. Run pm2 start app.js (replace app.js with your main file). PM2 will automatically detect the interpreter and start the process. You can also name the process: pm2 start app.js --name my-app.
  7. Check the process status. Run pm2 status to see a table of your processes, their status (online/stopped), CPU/memory usage, and restart counts.
  8. View logs. Use pm2 logs to see real-time logs from all processes. To see logs for a specific app, use pm2 logs my-app. Logs are also written to ~/.pm2/logs/.
  9. Set up startup on boot. Run pm2 startup. PM2 will output a command (like sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u youruser --hp /home/youruser) that you must copy and run with sudo. This creates a systemd service that starts PM2 on boot.
  10. Save your current process list. After running the startup command, run pm2 save. This saves your current process list so PM2 can restore it on reboot.
  11. Test the reboot configuration. Reboot your server (sudo reboot) and then check pm2 status after logging back in. Your app should be online automatically.
  12. Useful everyday commands. pm2 restart my-app restarts the app, pm2 stop my-app stops it, pm2 delete my-app removes it from PM2’s list, and pm2 monit opens a real-time monitoring dashboard.

Common Mistakes

  • Forgetting to run pm2 save after adding or removing apps. If you don’t save, the new list won’t be restored on reboot.
  • Running pm2 startup without sudo. The command needs root privileges to create the systemd service. Always copy and run the command it outputs with sudo.
  • Using pm2 start from the wrong directory. PM2 uses the current working directory to resolve relative paths. Always cd into the app folder first.
  • Not checking if the app actually starts. If your app has a syntax error, PM2 will show it as “errored” but might not exit. Check pm2 logs to see the actual error.
  • Ignoring the user that runs PM2. The startup command is tied to a specific user. If you start PM2 as root but the startup command is for another user, it won’t work.

Tips

  • Use a process file for complex apps. Instead of typing many CLI options, create an ecosystem.config.js file that defines your apps, their scripts, environment variables, and log settings. Then start with pm2 start ecosystem.config.js.
  • Set up log rotation. PM2 logs can grow large. Install pm2-logrotate with pm2 install pm2-logrotate to automatically rotate and compress logs.
  • Use --max-memory-restart to auto-restart on memory leaks. For example, pm2 start app.js --max-memory-restart 300M restarts the app if it exceeds 300 MB.
  • Run PM2 as a non-root user. For security, create a dedicated user for your apps and run PM2 under that user. The startup command will handle this if you run it as that user.
  • Monitor with pm2 monit. This gives a live view of CPU and memory usage for each process, which is helpful for debugging.

Troubleshooting

  • PM2 command not found. If you get pm2: command not found, the npm global bin directory is not in your PATH. Reinstall with sudo npm install -g pm2 and check the output for the install path. Add it to your PATH in ~/.bashrc if needed.
  • App shows “errored” status. Run pm2 logs my-app --err to see the error output. Common causes are missing dependencies, wrong file path, or port already in use.
  • App doesn’t restart after reboot. First, check if the PM2 systemd service is enabled: systemctl status pm2-. If it’s not active, run pm2 startup again and follow the output. Also ensure you ran pm2 save after starting your apps.
  • Port already in use. If your app fails to start because the port is taken, find the process with sudo lsof -i :3000 (replace port) and kill it with kill , or change your app’s port.
  • PM2 not responding. Sometimes the PM2 daemon can hang. Restart it with pm2 kill followed by pm2 start app.js to start fresh.
  • Environment variables not loading. If your app needs environment variables, define them in the ecosystem file or use pm2 start app.js --env production after setting them in the file. PM2 does not automatically load .env files unless you use a module like pm2-env or the dotenv package in your app.

Frequently Asked Questions

What is the difference between pm2 start and pm2 restart?

pm2 start is used to launch a process that is not currently running. pm2 restart stops and starts an already managed process, applying any code changes.

How do I update PM2 to the latest version?

Run sudo npm install -g pm2@latest and then pm2 update to refresh the daemon.

Can I use PM2 with Python or other languages?

Yes, PM2 can run any script. Use pm2 start script.py --interpreter python3 or specify the interpreter in the ecosystem file.

How do I make PM2 start my app with a specific Node.js version?

Use the --interpreter flag to point to the specific node binary, e.g., pm2 start app.js --interpreter /usr/local/bin/node.

Does PM2 work with cluster mode?

Yes, run pm2 start app.js -i max to start as many instances as there are CPU cores. This provides load balancing and high availability.

How do I remove PM2 from my server?

Stop all processes with pm2 kill, then uninstall with sudo npm uninstall -g pm2. Also remove the startup service with pm2 unstartup before uninstalling.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →