Configuring Packer

Packer's config directory

Packer's configuration directory can potentially contain plugins and internal Packer files. The Packer config directory will be looked up on the following paths:

Examples:

• On a Unix system, if the $PACKER_CONFIG_DIR environment variable is set to /home/packer, the config directory will be: /home/packer/.packer.d/ and other values will not be checked.
• On a Windows system, if the PACKER_CONFIG_DIR environment variable is set to C:/,the config directory will be: C:/packer.d/ and other values will not be checked.

Packer's config file (deprecated)

Packer can optionally read a JSON file for the end user to set core settings. The config file of Packer will be looked up on the following paths:

The format of the configuration file is basic JSON.

Packer config file configuration Reference

Below is the list of all available configuration parameters for the core configuration file. None of these are required, since all have defaults.

• plugin_min_port and plugin_max_port (number) - These are the minimum and maximum ports that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. By default these are 10,000 and 25,000, respectively. Be sure to set a fairly wide range here, since Packer can easily use over 25 ports on a single run.

• builders, commands, post-processors, and provisioners are objects that are used to install plugins. The details of how exactly these are set is covered in more detail in the installing plugins documentation page. It is instead recommended to use HCL2 required_plugins and the packer init command to install plugins; if you are using both, the required_plugin config will take precedence.

Packer's plugin directory

Upon the initialization of Packer, any externally installed plugin will be automatically discovered and loaded.

Packer plugins will usually be located within a plugins sub-directory under Packer's main config directory PACKER_CONFIG_DIR. If PACKER_CONFIG_DIR is either not set or empty, a default equal to $HOME/.config/packer/plugins on UNIX, or %APPDATA%\packer.d\plugins for Windows, will be used.

Where applicable, some installation processes such as packer init may override the plugin loading process. Refer to the specific installation guides for any plugin loading overrides.

Packer uses the following process for loading the correct plugin:

1. All directories under the PACKER_PLUGIN_PATH environment variable, if PACKER_PLUGIN_PATH is set. The PACKER_PLUGIN_PATH takes precedences over all other plugin directories; no other directories will be checked.
2. The directory where packer is installed, or the executable directory.
3. The current working directory, where packer build is being invoked. (".")
4. The PACKER_CONFIG_DIR/plugins directory. PACKER_CONFIG_DIR refers to Packer's config directory, if it could be found.

Packer's cache directory

Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches things in the current directory, under: ./packer_cache/. This can be changed by setting the PACKER_CACHE_DIR env var. It is recommended to share the same Packer cache directory across your builds if you have multiple builds doing similar things to avoid downloading the same ISO twice for example.

Environment Variables usable for Packer

Packer uses a variety of environmental variables. A listing and description of each can be found below:

• PACKER_CACHE_DIR - The location of the Packer cache. This defaults to ./packer_cache/. Relative paths can be used. Some plugins can cache large files like ISOs in the cache dir.

• PACKER_CONFIG - The location of the core configuration file. The format of the configuration file is basic JSON. See Packer's Config file.

• PACKER_CONFIG_DIR - The location for the home directory of Packer. See Packer's home directory for more.

• PACKER_GITHUB_API_TOKEN - When using Packer init on HCL2 templates, Packer queries the public API from Github which limits the amount of queries on can set the PACKER_GITHUB_API_TOKEN with a Github Token to make it higher.

• PACKER_LOG - Setting this to any value other than "" (empty string) or "0" will enable the logger. See the debugging page.

• PACKER_LOG_PATH - The location of the log file. Note: PACKER_LOG must be set for any logging to occur. See the debugging page.

• PACKER_NO_COLOR - Setting this to any value will disable color in the terminal.

• PACKER_PLUGIN_MAX_PORT - The maximum port that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. The default is 25,000. This can also be set using the Packer's config file, see the config file configuration reference for more.

• PACKER_PLUGIN_MIN_PORT - The minimum port that Packer uses for communication with plugins, since plugin communication happens over TCP connections on your local host. The default is 10,000. This can also be set using the Packer's config file, see the config file configuration reference for more.

• PACKER_PLUGIN_PATH - a PATH variable for finding third-party packer plugins. For example: ~/custom-dir-1:~/custom-dir-2. Separate directories in the PATH string using a colon (:) on POSIX systems and a semicolon (;) on Windows systems. The above example path would be able to find a provisioner named packer-provisioner-foo in either ~/custom-dir-1/packer-provisioner-foo or ~/custom-dir-2/packer-provisioner-foo. See the documentation on plugin directories for more.

• CHECKPOINT_DISABLE - When Packer is invoked it sometimes calls out to checkpoint.hashicorp.com to look for new versions of Packer. If you want to disable this for security or privacy reasons, you can set this environment variable to 1.

• TMPDIR (Unix) / TMP TEMP USERPROFILE (Windows) - The location of the directory used for temporary files (defaults to /tmp on Linux/Unix and %USERPROFILE%\AppData\Local\Temp on Windows Vista and above). It might be necessary to customize it when working with large files since /tmp is a memory-backed filesystem in some Linux distributions in which case /var/tmp might be preferred.