Skip to main content

Ansible module to manage processes via PM2

Project description

Github Actions PyPI version Code style: black


Ansible Module to Manage Processes via PM2

  • Manage the state of processes via pm2 process manager
  • Start/Stop/Restart/Reload/Delete applications

Tested on:

  • Host Python: 3.8
  • Target host Python: 2.7, 3.5, 3.6, 3.7, 3.8
  • Ansible: 2.8.10, 2.9.6 (Should work with older versions)


Install via pip:

pip install ansible-modules-pm2

PM2 package have to be installed to target hosts. For example, add following to your playbook to install pm2 globally:

- npm:
    name: pm2
    global: yes


Basic usage is similar to service or supervisorctl module: specify the name and its state. To start an app, give either script or config.


- name: Start myapp with process config file, if not running
    name: myapp
    config: /path/to/myapp/myapp.json
    state: started

- name: Start myapp.js, if not running
    name: myapp
    script: /path/to/myapp/myapp.js
    state: started

- name: Stop process named myapp, if running
    name: myapp
    state: stopped

- name: Restart myapp, in all cases
    name: myapp
    state: restarted

- name: Reload myapp, in all cases
    name: myapp
    state: reloaded

- name: Delete myapp, if exists
    name: myapp
    state: absent

- name: Specify pm2 executable path
    name: myapp
    state: started
    config: /path/to/myapp/myapp.json
    executable: /path/to/myapp/node_modules/.bin/pm2

- name: Also specify working directory where running pm2 command
    name: myapp
    state: started
    config: /path/to/myapp/myapp.json
    executable: /path/to/myapp/node_modules/.bin/pm2
    chdir: /path/to/working/directory


Parameters Choices Comments
name (required) Name of the application.
Required for all cases to check current status of app
state started (default)
started/stopped/absent/deleted are idempotent actions that will not run commands unless necessary.
restarted will always restart the process.
reloaded will always reload.
Note that restarted will fail when the process does not exist (action does not start it automatically).
config Process configuration file, in JSON or YAML format.
Either config or script is required when state=started.
script Executalbe file to start.
Either config or script is required when state=started.
executable Path to pm2 executable.
chdir Change into this directory before running pm2 start command.
When state=started and this option is omitted, use the directory where config or script exists.


This software is licensed under GPLv3. See LICENSE for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansible-modules-pm2-0.1.0.tar.gz (23.1 kB view hashes)

Uploaded Source

Built Distribution

ansible_modules_pm2-0.1.0-py3-none-any.whl (18.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page