Environment Variables

When starting a new process

PM2 will inject environment in this order when starting a new process :

• First the PM2 CLI will use its environment so the current environment of your shell will be injected. Since PM2 7.1.0, shell variables named like a PM2 option (name, namespace, instances, port, watch…) or prefixed with pm_/axm_ are not passed, and filter_env can drop more.
• PM2 will then inject the environment that you can configure with the ecosystem file (it always wins over the shell) :

module.exports = {
  apps : [
      {
        name: "myapp",
        script: "./app.js",
        watch: true,
        env: {
          "NODE_ENV": "development",
        }
      }
  ]
}

Here you can see that PM2 will override the current environment to add NODE_ENV=development. But you can also define different environments like this :

module.exports = {
  apps : [
      {
        name: "myapp",
        script: "./app.js",
        watch: true,
        env: {
            "PORT": 3000,
            "NODE_ENV": "development"
        },
        env_production: {
            "PORT": 80,
            "NODE_ENV": "production",
        }
      }
  ]
}

Here the default environment is in the env, but you can decide to use env_production by using pm2 start ecosystem.config.js --env production.

You can define as many environments as you like, just remember that you must pass the name of the environment (after env_) you want to use with --env.

Filtering the shell environment

Use filter_env to restrict what the app inherits from the shell running pm2 (and, in cluster mode, from the daemon):

Variables declared in env (or the selected env_<name>) are always passed:

module.exports = {
  apps : [{
    name: "myapp",
    script: "./app.js",
    filter_env: true,
    env: {
      NODE_ENV: "production"
    }
  }]
}

Via CLI, --filter-env alone means true, --filter-env AWS_ drops the variables containing AWS_. The filter also applies to --update-env restart/reload and to cluster workers.

Breaking change in PM2 7.1.2: filter_env: true was ignored since 4.4.1 and works again. Apps using it no longer inherit NODE_ENV, NODE_OPTIONS, HTTP_PROXY or any other shell variable: declare them in env. An app that already received the full shell env (started before 7.1.2 or without filter_env, dump.pm2 included) keeps it: pm2 delete it and start it again.

Specific environment variables

NODE_APP_INSTANCE (PM2 2.5 minimum)

There is the NODE_APP_INSTANCE environment variable that is used to make a difference between process, for example you may want to run a cronjob only on one process, you can just check if process.env.NODE_APP_INSTANCE === '0'. Two processes can never have the same number, its still true after pm2 restart and pm2 scale commands.

You may have problems with node-config with the NODE_APP_INSTANCE name, so you can rename it with instance_var options :

module.exports = {
  apps : [
      {
        name: "myapp",
        script: "./app.js",
        watch: true,
        instance_var: 'INSTANCE_ID',
        env: {
            "PORT": 3000,
            "NODE_ENV": "development"
        }
      }
  ]
}

In this case the variable will have the same behavior but will be in process.env.INSTANCE_ID.

increment_var (PM2 2.5 minimum)

There is an option to ask PM2 to increment an environment variable for each instance launched, for example:

module.exports = {
  apps : [
      {
        name: "myapp",
        script: "./app.js",
        instances: 2,
        exec_mode: "cluster",
        watch: true,
        increment_var : 'PORT',
        env: {
            "PORT": 3000,
            "NODE_ENV": "development"
        }
      }
  ]
}

In this example, if i run pm2 start ecosystem.config.js :

• PM2 will see that i want to increment the PORT variable for each instance
• It will see that i have defined the default to 3000
• The first instance will have process.env.PORT = 3000 and the second process.env.PORT = 3001

NOTE : It will increment also when scaling using pm2 scale myapp 4, both new instances will have 3002 and 3003 as PORT variable.

PM2 environment variables

These variables configure PM2 itself. Daemon-side ones are read when the daemon starts: run pm2 kill (or pm2 update) after changing them.