Installing and managing modules from the command line

Install, upgrade, and uninstall Forge modules from the command line with the puppet module command.

The puppet module command provides an interface for managing modules from the Forge. Its interface is similar to other common package managers, such as gem, apt-get, or yum. You can install, upgrade, uninstall, list, and search for modules with this command.

Restriction: If you are using Code Manager or r10k, do not install, update, or uninstall modules with the puppet module command. With code management, you must install modules with a Puppetfile. Code management purges modules that were installed with the puppet module command. See the Puppetfile documentation for instructions.

Setting up `puppet module` behind a proxy

To use the puppet module command behind a proxy, set the proxy's IP address and port by running the following two commands:

export http_proxy=http://<PROXY IP>:<PROXY PORT>
export https_proxy=http://<PROXY IP>:<PROXY PORT>

For instance, for an proxy at 192.168.0.10 on port 8080, run:

export http_proxy=http://192.168.0.10:8080
export https_proxy=http://192.168.0.10:8080

Alternatively, you can set these two proxy settings in the puppet.conf file, by setting http_proxy_host and http_proxy_port in the user section of puppet.conf. For more information, see the Puppet configuration reference.

Important: Set these two proxy settings only in the [user] section of the puppet.conf file. Setting them in other sections can cause problems.

Finding Forge modules

Visit the Forge website to search for and browse modules. Each module on the Forge has its own page with the module's quality score, community rating, and documentation.

Some modules are Puppet supported or Puppet approved. Approved modules are often developed by Puppet community members and pass our specific quality and usability requirements. We recommend these modules, but they are not supported as part of a Puppet Enterprise license agreement. Puppet supported modules have been tested with PE and are fully supported. To learn more, see the Puppet Approved Modules and Puppet Supported Modules pages.

If there are no supported or approved modules that meet your needs, you can evaluate available modules by compatibility, documentation, last release date, number of downloads, and the module's Forge quality score.

Note: It is no longer possible to search for modules on the command line. The puppet module search command was deprecated in Puppet 6.16.0.

Finding and downloading deleted modules

You can still search for and download a specific release of a module on the Forge, even if the release has been deleted.

Normally, deleted modules do not appear in Forge search results. To include deleted modules in your search on the Forge website, check Show deprecated modules in the search filter panel.

To download a deleted release of a specific module, select the release from the Select another release drop-down list on the module's page. The release is marked in this menu as deleted. If you select the deleted release, a warning banner appears on the page with the reason for deletion. To download the deleted release anyway, click Download or install it with the puppet module install command.

Installing modules from the command line

The puppet module install command installs a module and all of its dependencies. You can install modules from the Forge, a module repository, or a release tarball.

By default, this command installs modules into the first directory in the Puppet modulepath, which defaults to $codedir/environments/production/modules. For example, to install the puppetlabs-apache module, run:

puppet module install puppetlabs-apache

You can customize the module version, installation directory, or environment, get debugging information, or ignore dependencies by passing options with the puppet module install command.

Note: If any installed module has an invalid version number, Puppet issues a warning:

Warning: module (/Users/youtheuser/.puppet/modules/module) has an invalid 
version number (0.1). The version has been set to 0.0.0. If you are the maintainer for this module, please update the 
metadata.json with a valid Semantic Version (http://semver.org).

Despite the warning, Puppet still downloads your module and does not permanently change the module's metadata. The version is changed only in memory during the run of the program, so that Puppet can calculate dependencies.

Restriction: For Premium Content offerings, you must log in to the Forge to access the module.

Installing modules from the Forge by using an internet connection

To install a module from the Forge by using an internet connection, run the

puppet module
                                        install

command with the long name of the module. The long name of a module is formatted as <username>-<modulename>. For example, to install puppetlabs-apache, run:

puppet module install puppetlabs-apache

Installing modules from the Forge in an air-gapped environment

You can install a module in an air-gapped environment in which the host server does not have internet access. In the following instructions, Security Compliance Enforcement (SCE) for Linux is used as an example. However, the general process applies to all Puppet modules.

If the module is a Premium Content offering (like the SCE modules), log in to Puppet Forge to gain access to the module.
In Puppet Forge, locate the module and download the release tarball. In the Installation Method list, click Direct download and Download.
Copy the downloaded tarball to the appropriate location. The location will be either the primary Puppet server and each compiler, or the source repository that hosts your control repository.
Install the Puppet module by using one of the following methods:
- Direct installation using the puppet module install command. You can install the module either into your Puppet environment or your control repository. Run a command that is similar to the following example, but specify the file, directory, and module that you require:
```
puppet module install ./puppetlabs-cem_linux-1.6.1.tar.gz --ignore-dependencies --modulepath </path/to/your/modules>
```
- Manual installation using a tar command. Run a command that is similar to the following example, but specify the file, directory, and module that you require:
```
tar zxvf puppetlabs-cem_linux-1.6.1.tar.gz && mv puppetlabs-cem_linux </path/to/your/modules>/cem_linux
```
For any module dependencies, repeat steps through 1-4.
If you installed the module to your control repository, commit and push the changes.

Installing from another module repository

You can install modules from other repositories that mimic the Forge interface. You can change the module repository for one installation, or you can change your default repository.

To change the module repository for a single module installation, specify the base URL of the repository on the command line with the --module_repository option. For example:

puppet module install --module_repository http://dev-forge.example.com puppetlabs-apache

To change the default module repository, edit the module_repository setting in the puppet.conf to the base URL of the repository you want to use. The default value for the module_repository is the Forge URL, https://forgeapi.puppetlabs.com. See the module_repository setting in the puppet.conf configuration documentation.

Installing from a release tarball

To install a module from a release tarball, specify the path to the tarball instead of the module name.

If you cannot connect to the Forge, or you are installing modules that have not yet been published to the Forge, use the --ignore-dependencies option and manually install any dependencies. For example:

puppet module install ~/puppetlabs-apache-0.10.0.tar.gz --ignore-dependencies

Installing and upgrading Puppet Enterprise-only modules

Some Puppet modules are available only to PE users. Generally, you manage these modules in the same way you would manage other modules. You can use these modules with licensed PE nodes, a PE 10-node trial license, or with Bolt for a limited evaluation period. See your module's license for complete details.

Install modules on nodes without internet

To manually install a module on a node with no internet, download the module on a connected machine, and then move a module package to the unconnected node. If the module is a PE-only module, the download machine must have a valid PE license.

Before you begin

Make sure you have PDK installed. You'll use PDK to build a module package that you can move to your unconnected node. For installation instructions, see the PDK install docs.

Tip: On machines with no internet access, you must install any module dependencies manually. Check your dependencies at the beginning of this process, so that you can move all of the necessary modules to the unconnected node at one time.

On a node with internet access, run puppet module install puppetlabs-<MODULE>
Change into the module's directory by running cd <MODULE_NAME>
Build a package from the installed module by running pdk build
Move the *.tar.gz to the machine on which you want to install the module.
Install the tar.gz package with the puppet module install command. For example:
```
puppet module install puppetlabs-pe_module-0.1.0.tar.gz
```
Manually install the module's dependencies. Without internet access, puppet module install cannot install dependencies automatically.

Uninstalling modules

Completely remove installed modules with the puppet module uninstall command.

This command uninstalls modules from the modulepath specified in the puppet.conf file. To remove a module, run the uninstall command with the full name of the module. For example:

puppet module uninstall puppetlabs-apache

By default, the command exits and returns an error if you try to uninstall a module that other modules depend on or if the module's files have been modified after it was installed. You can forcibly uninstall dependencies or changed modules with command line options.

For example, to uninstall a module that other modules depend on, run:

puppet module uninstall --force

See the puppet module command reference for a complete list of options.

`puppet module` command reference

The puppet module command manages modules with several actions and options.

`puppet module` actions


Action	Description	Arguments	Example
`build`	Deprecated. Prepares a local module for release on the Forge by building a ready-to-upload archive file. Will be removed in a future release; use Puppet Development Kit instead.	A valid directory path to a module.	`puppet module build modules/apache`
`changes`	Compares the files on disk to the md5 checksums and returns an array of paths of modified files.	A valid directory path to a module.	`puppet module changes /etc/code/modules/stdlib`
`install`	Installs a module.	The full name <`username-module_name`> of the module to uninstall.	`puppet module install puppetlabs-apache`
`list`	Lists the modules installed in the modulepath specified in the `[main]` block in the `puppet.conf` file.	None.	`puppet module list`
`search`	Deprecated. Visit the Forge to search for modules. This command searched the Forge for modules matching search values.	Deprecated.	Deprecated
`uninstall`	Uninstalls a module.	The full name <`username-module_name`> of the module to uninstall.	`puppet module uninstall puppetlabs-apache`
`upgrade`	Upgrades a module to the most recent release or to the specified version. Does not upgrade dependencies.	The full name <`username-module_name`> of the module to upgrade.	`puppet module upgrade puppetlabs-apache --version 0.0.3`

`puppet module install` action

Installs a module from the Forge or another specified release archive.

Usage:

puppet module install [--debug] [--environment] [--force | -f] [--ignore-dependencies]
  [--module_repository <REPOSITORY_URL>] [--strict-semver]
  [--target-dir <DIRECTORY/PATH> | -i <DIRECTORY/PATH>] [--version <x.x.x> | -v <x.x.x>]
  <full_module_name>

For example:

puppet module install --environment testing --ignore-dependencies 
  --version 1.0.0-pre1 --strict-semver false puppetlabs-apache


Option	Description	Value	Default
`--debug`, `-d`	Displays additional information about what the `puppet module` command is doing.	None.	If not specified, additional information is not displayed.
`--environment`	Installs the module into the specified environment.	An environment name.	By default, installs the module into the default environment specified in the `puppet.conf` file.
`--force`, `-f`	Installs the module regardless of dependency tree, checksum changes, or whether the module is already installed. By default, installs the module in the default modulepath, even if the module is already installed in another directory. Does not install dependencies.	None.	If not specified, `puppet module install` exits and returns information if it encounters installation errors or conflicts.
`--ignore-dependencies`	Does not install any modules required by this module.	None.	If not specified, the `puppet module install` action installs the module and its dependencies.
`--module_repository`	Specifies a module repository.	A valid URL for a module repository.	If not specified, installs modules from the module repository specified in from the `puppet.conf` file. By default, this is the URL for the Forge.
`--strict-semver`	Whether to exclude pre-release versions. A value of false allows installation of pre-release versions.	`true`, `false`	Defaults to `true`, excluding pre-release versions.
`--target-dir`, `-i`	Specifies a directory to install modules.	A valid directory path.	By default, installs modules into `$codedir/environments/production/modules`
`--version`, `-v`	Specifies the module version to install.	A semantic version number, such as 1.2.1 or a string specifying a requirement, such as ">=1.0.3".	If not specified, installs the most recent version available on the Forge.

`puppet module list` action

Lists the Puppet modules installed in the modulepath specified in the puppet.conf file's [main] block. Use the --modulepath option to change which directories are scanned.

Usage:

puppet module list [--tree] [--strict-semver]

For example:

puppet module list --tree --modulepath etc/testing/modules


Option	Description	Value	Default
`--modulepath`	Specifies another modulepath to scan for modules.	A valid directory path.	By default, scans the default modulepath from the `[main]` block in the `puppet.conf` file.
`--strict-semver`	Whether to exclude pre-release versions. A value of false allows uninstallation of pre-release versions.	`true`, `false`	Defaults to `true`, excluding pre-release versions.
`--tree`	Displays the module list as a tree showing dependencies.	None.	By default, `puppet module list` lists installed modules but does not show dependency relationships.

`puppet module uninstall` action

Uninstalls a module from the default modulepath.

Usage:

puppet module uninstall [--force | -f] [--ignore-changes | -c] [--strict-semver] [--version=]  <full_module_name>

For example:

puppet module uninstall --ignore-changes --version 0.0.2 puppetlabs-apache


Option	Description	Value	Default
`--force`, `-f`	Uninstalls the module regardless of dependency tree or checksum changes.	None.	By default, `puppet module uninstall` exits and returns an error if it encounters changes, namespace errors, or dependencies.
`--ignore-changes`	Does not use the checksum and uninstalls regardless of modified files.	None.	By default, if the `puppet module uninstall` action finds modified files in the module, it exits and returns an error.
`--strict-semver`	Whether to exclude pre-release versions. A value of false allows uninstallation of pre-release versions.	`true`, `false`	Defaults to `true`, excluding pre-release versions.
`--version`, `-v`	Specifies the module version to uninstall.	A semantic version number, such as 1.2.1 or a string specifying a requirement, such as ">=1.0.3"..	By default, `puppet module uninstall` uninstalls the version installed in the modulepath.

`puppet module upgrade` action

This command upgrades modules to the most recent released version of the module. This includes upgrades to the most recent major version.

Usage:

puppet module upgrade [--force | -f] [--ignore-changes | -c] [--ignore-dependencies] 
  [--strict-semver] [--version=] <full_module_name>

For example:

puppet module upgrade --force --version 2.1.2 puppetlabs-apache


Option	Description	Value	Default
`--force`, `-f`	Upgrades the module regardless of dependency tree or checksum changes.	None.	By default, `puppet module upgrade` exits and returns an error if it encounters changes, namespace errors, or dependencies.
`--ignore-changes`	Does not use the checksum and upgrades regardless of modified files.	None.	By default, if the `puppet module upgrade` action finds modified files in the module, it exits and returns an error.
`--ignore-dependencies`	Does not attempt to install any missing modules required by this module.	None.	If not specified, the `puppet module upgrade` action installs missing module dependencies.
`--strict-semver`	Whether version ranges must exclude pre-release versions.	`true`, `false`	Defaults to `true`, excluding pre-release versions.
`--version`, `-v`	Specifies the module version to uninstall.	A semantic version number, such as 1.2.1 or a string specifying a requirement, such as ">=1.0.3".	By default, `puppet module uninstall` uninstalls the version installed in the modulepath.

PE-only module troubleshooting

If you get an error when installing a PE-only module, check for common issues.

When installing or upgrading a PE-only module, you might get the following error:

Error: Request to Puppet Forge failed.
  The server being queried was https://forgeapi.puppetlabs.com/v3/releases?module=puppetlabs-f5&module_groups=base+pe_only
  The HTTP response we received was '403 Forbidden'
  The message we received said 'You must have a valid Puppet Enterprise license on this 
  node in order to download puppetlabs-f5. If you have a Puppet Enterprise license, 
  please see https://docs.puppetlabs.com/pe/latest/modules_installing.html#puppet-enterprise-modules
  for more information.'

If you aren't a PE user, you won't be able to use this module unless you purchase a PE license. If you are a PE user, check the following:

Are you logged in as the root user? If not, log in as root and try again.
Does the node you're on have a valid PE license? If not, switch to a node that has a valid license on it.
Are you running a version of PE that supports this module? If not, you might need to upgrade.
Does the node you are installing on have access to the internet? If not, switch to a node that has access to the internet.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.

Installing and managing modules from the command line

Setting up puppet module behind a proxy

Finding Forge modules

Finding and downloading deleted modules

Installing modules from the command line

Installing modules from the Forge by using an internet connection

Installing modules from the Forge in an air-gapped environment

Installing from another module repository

Installing from a release tarball

Installing and upgrading Puppet Enterprise-only modules

Install modules on nodes without internet

Uninstalling modules

puppet module command reference

puppet module actions

puppet module install action

puppet module list action

puppet module uninstall action

puppet module upgrade action

PE-only module troubleshooting

Setting up `puppet module` behind a proxy

`puppet module` command reference

`puppet module` actions

`puppet module install` action

`puppet module list` action

`puppet module uninstall` action

`puppet module upgrade` action