PM2 Python Library

Professional Python library for PM2 process management with comprehensive features, async support, and production-ready reliability.

Get Started View on GitHub
100% PM2 Compatible
Async Full Support
90%+ Test Coverage

Powerful Features

Complete Process Management

Start, stop, restart, reload, and delete PM2 processes with full lifecycle control.

Real-time Monitoring

Monitor CPU usage, memory consumption, uptime, and process metrics in real-time.

Async/Await Support

Full asynchronous programming support with context managers and async methods.

Error Handling

Comprehensive exception hierarchy with detailed error messages and recovery options.

Environment Variables

Complete environment variable management and configuration support.

Type Hints

Full type hint support for better IDE integration and code quality.

Installation

PyPI Installation

pip install pm2

Development Version

git clone https://github.com/y4kupkaya/PM2.git
cd PM2
pip install -e .

Requirements

  • Python 3.7+
  • PM2 installed globally (npm install -g pm2)
  • Optional: aiofiles for async file operations

Quick Start

Basic Usage

from pm2 import PM2Manager

# Initialize PM2 manager
pm2 = PM2Manager()

# Start a new process
process = pm2.start_app(
    script="app.js",
    name="my-app",
    env={"PORT": "3000", "NODE_ENV": "production"}
)

print(f"Started {process.name} with PID {process.pid}")

# Monitor the process
print(f"CPU: {process.metrics.cpu}%")
print(f"Memory: {process.metrics.memory_mb:.1f} MB")

# List all processes
processes = pm2.list_processes()
for proc in processes:
    print(f"{proc.name}: {proc.status.value}")

# Stop and delete
pm2.stop_process("my-app")
pm2.delete_process("my-app")

Async Usage

import asyncio
from pm2 import PM2Manager

async def main():
    pm2 = PM2Manager()
    
    # Use async context manager
    async with pm2.async_context() as pm2_async:
        # Start process asynchronously
        process = await pm2_async.start_app_async(
            script="app.js",
            name="async-app"
        )
        
        # List processes asynchronously
        processes = await pm2_async.list_processes_async()
        
        # Clean up
        await pm2_async.delete_process_async("async-app")

asyncio.run(main())

Documentation & Resources

API Reference

Complete API documentation with all classes, methods, and parameters.

Code Examples

Practical examples and use cases for real-world applications.

Advanced Usage

Advanced features, async patterns, and best practices.

Troubleshooting

Common issues, solutions, and debugging tips.

Code Examples

# Process lifecycle management
pm2 = PM2Manager()

# Start with environment variables
process = pm2.start_app(
    script="server.js",
    name="web-server",
    env={
        "PORT": "3000",
        "NODE_ENV": "production",
        "DATABASE_URL": "mongodb://localhost:27017/myapp"
    }
)

# Restart gracefully
pm2.reload_process("web-server")

# Scale to multiple instances
pm2.restart_process("web-server", instances=4)
# Real-time monitoring
processes = pm2.list_processes()

for process in processes:
    print(f"📊 {process.name}")
    print(f"   PID: {process.pid}")
    print(f"   Status: {process.status.value}")
    print(f"   CPU: {process.metrics.cpu}%")
    print(f"   Memory: {process.metrics.memory_mb:.1f} MB")
    print(f"   Uptime: {process.uptime_seconds}s")
    print(f"   Restarts: {process.restart_time}")
    print()
# Comprehensive error handling
from pm2 import PM2Manager, PM2Error, PM2ProcessNotFoundError

try:
    pm2 = PM2Manager()
    process = pm2.start_app("nonexistent.js", name="test")
    
except PM2ProcessNotFoundError as e:
    print(f"Process not found: {e}")
    
except PM2Error as e:
    print(f"PM2 error: {e.message}")
    print(f"Details: {e.details}")
    
except Exception as e:
    print(f"Unexpected error: {e}")

About PM2 Integration

Legal Notice & Attribution

This library is an independent Python wrapper for the PM2 Process Manager. PM2 is a separate open-source project developed by Keymetrics/Unitech. This Python library is not affiliated with, endorsed by, or officially supported by the PM2 team.

This wrapper library communicates with PM2 through its command-line interface and does not modify or redistribute any PM2 code. Users must install PM2 separately. All PM2 trademarks and copyrights belong to their respective owners.

Our License: This Python library is distributed under the GNU General Public License v3.0 (GPL-3.0). This is completely separate from PM2's MIT license and allows us to create independent tools that interact with PM2.