packer/website/content/docs/configure.mdx

---
description: |
  Learn how to configure Packer's global behavior using environment variables.
page_title: Configure Packer
---

# Configure Packer

This topic describes how to configure Packer. The default configurations are suitable for learning how to get started, but you should refer to this topic for guidance as you become more familiar with Packer.

## Overview

You can set Packer-specific environment variables in a configuration file to configure Packer behavior globally. Install configuration files in the Packer configuration directory to implement the configurations. You can also install plugin files and their SHA256SUM files to the plugins subdirectory under the configuration directory. Refer to [Installing Plugins](/packer/docs/plugins/install) for instructions.

You can also define Packer settings in a JSON configuration file and add it to the execution path. This configuration method is deprecated.

## Install a configuration file

You can place internal configuration files into Packer's `config` directory. Packer checks the following paths for configuration files:

| OS | Path | Notes |
| --- | ---| --- |
| Unix | `${HOME}/.config/packer/` | Packer follows the XDG base directory specification by default. As a result, Packer uses `$HOME/.config/packer` as the default directory when the `PACKER_CONFIG_DIR` environment variable is unset or empty. Packer ignores the XDG specification when the `PACKER_CONFIG_DIR` variable is set or when the installation uses legacy `.packer.d`-style directories, for example `$HOME/.packer.d/`. Refer to the [XDG specification](https://specifications.freedesktop.org/basedir-spec/latest/) for additional information. |
| Windows | `%APPDATA%\packer.d\` | |


### Examples

- **Unix**: If `$PACKER_CONFIG_DIR` is set to `/home/packer`, then the configuration directory is `/home/packer/.packer.d/`. Packer does not check other values.
- **Windows**: If `PACKER_CONFIG_DIR` is set to `C:/`, then the configuration directory is `C:/packer.d/`. Packer does not check other values.


<a id="packer-s-config-file"></a>

##  Install a JSON configuration file

This installation method is deprecated since 1.7. Instead, use the [HCL2
`required_plugins` block](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) to configure how Packer installs plugins. 

You use a JSON file to set core Packer settings. Packer checks the following paths for the configuration file:

| Unix                             | Windows                           |
| -------------------------------- | --------------------------------- |
| `${PACKER_CONFIG}`               | `%PACKER_CONFIG%`                 |
| `${HOME}/.packerconfig`          | `%APPDATA%\packer.config\`        |


### JSON configuration file reference 

Use basic JSON to configure the file. You can specify the configuration parameters for the core
configuration file. All parameters are optional. None of these are required, since all have defaults.

- `plugin_min_port`: Number that specifies the lowest port that Packer can use for communicating with plugins. Packer communicates with plugins over TCP or Unix sockets on your local host. Default is `10000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run.
- `plugin_max_port`: Number that specifies highest port that Packer can for communicating with plugins. Packer communicates with plugins over TCP  connections on your local Unix host. Default is `25000`. We recommend setting a wide range between `plugin_min_port` and `plugin_max_port` so that Packer has access to at least 25 ports on a single run.

The [`packer init`](/packer/docs/commands/init) command takes precedence over JSON-configure settings when installing plugins.


## Configure the cache directory

Packer uses a cache directory to download large files and for logistics around large file download. By default, Packer caches files in the `.packer_cache` folder of the current directory. Use the `PACKER_CACHE_DIR` environment variable to configure the cache directory. Refer to [`PACKER_CACHE_DIR`](/packer/docs/configure#packer_config_dir) for details.

We recommend using the same Packer cache directory across your builds if multiple builds perform similar actions. This is to avoid downloading the same large file, such as an ISO, multiple times.


## Configuration reference

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-s-config-file).

- `PACKER_CONFIG_DIR` - The location for the home directory of Packer. See
  [Packer's home directory](#packer-s-home-directory) for more.

- `PACKER_GETTER_READ_TIMEOUT` - Override the timeout when a packer plugin
  tries to fetch a ISO. The default is `30m`. This is specified as a string with
  a duration suffix.  The plugin needs to be built on 
  [v0.6.0](https://github.com/hashicorp/packer-plugin-sdk/releases/tag/v0.6.0)
  and above of the SDK to be compatible with this variable.

- `PACKER_GITHUB_API_TOKEN` - When using Packer init on HCL2 templates, Packer
  queries the public API from GitHub which has rate-limits on its APIs.
  You can set the `PACKER_GITHUB_API_TOKEN` environment variable
  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/docs/debugging).

- `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/docs/debugging).

- `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](#packer-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](#packer-config-file-configuration-reference) for more.

- `PACKER_PLUGIN_PATH` - a PATH variable for finding packer plugins. This takes
     precedence over `PACKER_CONFIG_DIR/plugins` for plugin discovery if
     defined. Plugin installation requires access to temporary files under
     `TMPDIR`. If the system's temp directory is non-writable or non-executable,
     refer to `TMPDIR` to override the location of the temporary file store used by
     Packer.

- `CHECKPOINT_DISABLE` - When Packer is invoked it sometimes calls out to
  [checkpoint.hashicorp.com](https://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) - This specifies the
     directory for temporary files (defaulting to `/tmp` on Linux/Unix and
     `%USERPROFILE%\AppData\Local\Temp` on Windows Vista and later). Customizing
     this setting might be necessary for systems where the default temporary
     directory is either non-writable or non-executable.