Installing and managing modules from the command line
Install, upgrade, and uninstall Forge modules from the command line with the
puppet module command.
module command provides an interface for managing modules from the Forge. Its interface is similar to other common
package managers, such as
yum. You can install,
upgrade, uninstall, list, and search for modules with this command.
puppet modulecommand. With code management, you must install modules with a Puppetfile. Code management purges modules that were installed with the
puppet modulecommand. See the Puppetfile documentation for instructions.
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>
Alternatively, you can set these two proxy settings in the
export http_proxy=http://192.168.0.10:8080 export https_proxy=http://192.168.0.10:8080
puppet.conffile, by setting
puppet.conf. For more information, see the Puppetconfiguration reference.
[user] section of the
puppet.conffile. Setting them in other sections can cause problems.
Finding Forge modules
The Forge houses thousands of modules, which you can find on the Forge website or by searching on the command line.
The easiest way to search for or browse modules is on the Forge website. Each module on the Forge has its own page with the module's
quality score, community rating, and documentation. Alternatively, you can search for
modules on the command line with the
module search command.
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 and Puppet supported pages.
If there are no supported or approved modules that meet your needs, evaluate available modules by compatibility, documentation, last release date, number of downloads, and the module's Forge quality score.
Searching modules from the command line
puppet module search command accepts a single search term and returns
a list of modules whose names, descriptions, or keywords match the search term.
returns results such as:
puppet module search apache
Searching http://forge.puppetlabs.com ... NAME DESCRIPTION AUTHOR KEYWORDS puppetlabs-apache This is a generic ... @puppetlabs apache web puppetlabs-passenger Module to manage P... @puppetlabs apache DavidSchmitt-apache Manages apache, mo... @DavidSchmitt apache jamtur01-httpauth Puppet HTTP Authen... @jamtur01 apache jamtur01-apachemodules Puppet Apache Modu... @jamtur01 apache adobe-hadoop Puppet module to d... @adobe apache
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 Include deleted 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
Installing modules from the command line
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
$codedir/environments/production/modules. For example, to install the
puppet module install pupppetlabs-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.
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.
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).
Installing modules from the Forge
puppet module installcommand with the long name of the module. The long name of a module is formatted as
<username>-<modulename>. For example, to install
puppet module install puppetlabs-apache
puppet module install command, you'll get an error like:
This error occurs because there is no CA-cert bundle on Solaris 10 to trust the Forge certificate. To work around this issue, download the module from the Forge website, and then install the module tarball with the
Error: Could not connect via HTTPS to https://forgeapi.puppetlabs.com Unable to verify the SSL certificate The certificate may not be signed by a valid CA The CA bundle included with OpenSSL may not be valid or up to date
puppet module installcommand, as described in the topic about installing from a release tarball.
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.
--module_repositoryoption. For example:
To change the default module repository, edit the
puppet module install --module_repository http://dev-forge.example.com puppetlabs-apache
module_repositorysetting in the
puppet.confto the base URL of the repository you want to use. The default value for the
module_repositoryis the Forge URL,
https://forgeapi.puppetlabs.com. See the
module_repositorysetting in the
Installing from a release tarball
To install a module from a release tarball, specify the path to the tarball instead of the module name.
--ignore-dependenciesoption 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, but you must have a valid PE license on the machine on which you download the module.
puppet modulecommand, you must:
Be logged in as the root user.
Install the module on a PE-licensed node.
Have internet access on the machine you are using to download modules.
librarian-puppetto manage PE modules, you must first install the module, and then commit the module to your version control repository.
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.
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.
On a node with internet access, run
puppet module install puppetlabs-<MODULE>
Change into the module's directory by running
Build a package from the installed module by
*.tar.gzto the machine on which you want to install the module.
tar.gzpackage with the
puppet module installcommand. For example:
puppet module install puppetlabs-pe_module-0.1.0.tar.gz
Manually install the module's dependencies.
Without internet access,
puppet module installcannot install dependencies automatically.
To upgrade a module to a newer version, use the
puppet module upgrade
This command upgrades modules to the most recent released version of the module. This includes upgrading the module to the most recent major version.
puppet module upgrade puppetlabs-apache
--versionoption. For example, to upgrade
puppetlabs-apacheversion 2.2.0 without any breaking changes, specify the 2.x release to upgrade to:
puppet module upgrade puppetlabs-apache --version 2.3.1
You can also ignore changes or dependencies when upgrading with
command line options. See the
puppet module command reference for a complete list of options.
Completely remove installed modules with the
puppet module uninstall
puppet.conffile. 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 since it was installed. You can forcibly uninstall dependencies or changed modules with command line options.
puppet module uninstall --force
puppet modulecommand reference for a complete list of options.
module command reference
The puppet module command manages modules with several actions and options.
puppet module actions
Note: To use
module commands on Solaris systems, you must first install
||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.||
||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.||
||Installs a module.||The full name <
||Lists the modules installed in the modulepath
specified in the
||Searches the Forge for modules matching search values.||A single search term.||
||Uninstalls a module.||The full name <
||Upgrades a module to the most recent release or to the specified version. Does not upgrade dependencies.||The full name <
puppet module install action
Installs a module from the Forge or another specified release archive.
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>
puppet module install --environment testing --ignore-dependencies --version 1.0.0-pre1 --strict-semver false puppetlabs-apache
||Displays additional information about what the
||None.||If not specified, additional information is not displayed.|
||Installs the module into the specified environment.||An environment name.||By default, installs the module into the default
environment specified in the
||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,
||Does not install any modules required by this module.||None.||If not specified, the
||Specifies a module repository.||A valid URL for a module repository.||If not specified, installs modules from the
module repository specified in from the
||Whether to exclude pre-release versions. A value of false allows installation of pre-release versions.||
||Specifies a directory to install modules.||A valid directory path.|| By default, installs modules into
||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
[main] block. Use the
--modulepath option to change which directories are
puppet module list [--tree] [--strict-semver]
puppet module list --tree --modulepath etc/testing/modules
||Specifies another modulepath to scan for modules.||A valid directory path.||By default, scans the default modulepath from
||Whether to exclude pre-release versions. A value of false allows uninstallation of pre-release versions.||
||Displays the module list as a tree showing dependencies.||None.||By default,
puppet module uninstall action
Uninstalls a module from the default modulepath.
puppet module uninstall [--force | -f] [--ignore-changes | -c] [--strict-semver] [--version=] <full_module_name>
puppet module uninstall --ignore-changes --version 0.0.2 puppetlabs-apache
||Uninstalls the module regardless of dependency tree or checksum changes.||None.||By default,
||Does not use the checksum and uninstalls regardless of modified files.||None.||By default, if the
||Whether to exclude pre-release versions. A value of false allows uninstallation of pre-release versions.||
||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 upgrade action
This command upgrades modules to the most recent released version of the module. This includes upgrades to the most recent major version.
puppet module upgrade [--force | -f] [--ignore-changes | -c] [--ignore-dependencies] [--strict-semver] [--version=] <full_module_name>
puppet module upgrade --force --version 2.1.2 puppetlabs-apache
||Upgrades the module regardless of dependency tree or checksum changes.||None.||By default,
||Does not use the checksum and upgrades regardless of modified files.||None.||By default, if the
||Does not attempt to install any missing modules required by this module.||None.||If not specified, the
||Whether version ranges should exclude pre-release versions.||
||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,
PE-only module troubleshooting
If you get an error when installing a PE-only module, check for common issues.
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.