The modulepath

The primary server service and the puppet apply command load most of their content from modules found in one or more directories. The list of directories where Puppet looks for modules is called the modulepath. The modulepath is set by the current node's environment.

The modulepath is an ordered list of directories, with earlier directories having priority over later ones. Use the system path separator character to separate the directories in the modulepath list. On *nix systems, use a colon (:); on Windows use a semi-colon (;).

For example, on *nix: 
/etc/puppetlabs/code/environments/production/modules:/etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules
On Windows: 
C:/ProgramData/PuppetLabs/code/environments/production/modules;C:/ProgramData/PuppetLabs/code/modules

Each directory in the modulepath must contain only valid Puppet modules, and the names of those modules must follow the modules naming rules. Dashes and periods in module names cause errors. For more information, see Modules fundamentals.

By default, the modulepath is set by the current node's environment in environment.conf. For example, using *nix paths:
modulepath = site:dist:modules:$basemodulepath
To see what the modulepath is for an environment, run:
sudo puppet config print modulepath --section server --environment <ENVIRONMENT_NAME>
For more information about environments, see Environments.

Setting the modulepath and base modulepath

Each environment sets its full modulepath in the environment.conf file with the modulepath setting. The modulepath setting can only be set in environment.conf. It configures the entire modulepath for that environment.

The modulepath can include relative paths, such as ./modules or ./site. Puppet looks for these paths inside the environment’s directory.

The default modulepath value for an environment is the environment’s modules directory, plus the base modulepath. On *nix, this is ./modules:$basemodulepath.

The base modulepath is a list of global module directories for use with all environments. You can configure it with the basemodulepath setting in the puppet.conf file, but its default value is probably suitable. The default on *nix:
$codedir/modules:/opt/puppetlabs/puppet/modules
On Windows:
$codedir\modules
If you want an environment to have access to the global module directories, include $basemodulepath in the environment's modulepath setting:
modulepath = site:dist:modules:$basemodulepath

Using the --modulepath option with Puppet apply

When running Puppet apply on the command line, you can optionally specify a modulepath with the --modulepath option, which overrides the modulepath from the current environment.

Absent, duplicate, and conflicting content from modules

Puppet uses modules it finds in every directory in the modulepath. Directories in the modulepath can be empty or absent. This is not an error; Puppet does not attempt to load modules from those directories. If no modules are present across the entire modulepath, or if modules are present but none of them contains a lib directory, the agent logs an error when attempting to sync plugins from the primary server. This error is benign and doesn't prevent the rest of the run.

If the modulepath contains multiple modules with the same name, Puppet uses the version from the directory that comes earliest in the modulepath. Modules in directories earlier in the modulepath override those in later directories.

For most content, this earliest-module-wins behavior is on an all-or-nothing, per-module basis — all of the manifests, files, and templates in the first-encountered version are available for use, and none of the content from any subsequent versions is available. This behavior covers:

  • Puppet code (from manifests).

  • Files (from files).

  • Templates (from templates).

  • External facts (from facts.d).

  • Ruby plugins synced to agent nodes (from lib).

CAUTION: Puppet sometimes displays unexpected behavior with Ruby plugins that are loaded directly from modules. This includes:

  • Plugins used by the primary server (custom resource types, custom functions).

  • Plugins used by puppet apply.

  • Plugins present in the agent’s modulepath (which is usually empty but night not be when running an agent on a node that is also a primary server).

In this case, the plugins are handled on a per-file basis instead of per-module. If a duplicate module in an later directory has additional plugin files that don’t exist in the first instance of the module, those extra files are loaded, and Puppet uses a a mixture of files from both versions of the module.

If you refactor a module’s Ruby plugins, and maintain two versions of that module in your modulepath, it can have unexpected results.

This is a byproduct of how Ruby works and is not intentional or controllable by Puppet; a fix is not expected.