---
description: |
  The post-processor section within a template configures any post-processing
  that will be done to images built by the builders. Examples of post-processing
  would be compressing files, uploading artifacts, etc.
layout: docs
page_title: Post-Processors - Templates
sidebar_title: Post-Processors
---

# Template Post-Processors

The post-processor section within a template configures any post-processing
that will be done to images built by the builders. Examples of post-processing
would be compressing files, uploading artifacts, etc.

Post-processors are _optional_. If no post-processors are defined within a
template, then no post-processing will be done to the image. The resulting
artifact of a build is just the image outputted by the builder.

This documentation page will cover how to configure a post-processor in a
template. The specific configuration options available for each post-processor,
however, must be referenced from the documentation for that specific
post-processor.

Within a template, a section of post-processor definitions looks like this:

```json
{
  "post-processors": [
    // ... one or more post-processor definitions here
  ]
}
```

For each post-processor definition, Packer will take the result of each of the
defined builders and send it through the post-processors. This means that if
you have one post-processor defined and two builders defined in a template, the
post-processor will run twice (once for each builder), by default. There are
ways, which will be covered later, to control what builders post-processors
apply to, if you wish. It is also possible to prevent a post-processor from
running.

## Post-Processor Definition

Within the `post-processors` array in a template, there are three ways to
define a post-processor. There are _simple_ definitions, _detailed_
definitions, and _sequence_ definitions. Another way to think about this is
that the "simple" and "detailed" definitions are shortcuts for the "sequence"
definition.

A **simple definition** is just a string; the name of the post-processor. An
example is shown below. Simple definitions are used when no additional
configuration is needed for the post-processor.

```json
{
  "post-processors": ["compress"]
}
```

A **detailed definition** is a JSON object. It is very similar to a builder or
provisioner definition. It contains a `type` field to denote the type of the
post-processor, but may also contain additional configuration for the
post-processor. A detailed definition is used when additional configuration is
needed beyond simply the type for the post-processor. An example is shown
below.

```json
{
  "post-processors": [
    {
      "type": "compress",
      "format": "tar.gz"
    }
  ]
}
```

A **sequence definition** is a JSON array comprised of other **simple** or
**detailed** definitions. The post-processors defined in the array are run in
order, with the artifact of each feeding into the next, and any intermediary
artifacts being discarded. A sequence definition may not contain another
sequence definition. Sequence definitions are used to chain together multiple
post-processors. An example is shown below, where the artifact of a build is
compressed then uploaded, but the compressed result is not kept.

It is very important that any post processors that need to be run in order, be
sequenced!

```json
{
  "post-processors": [
    ["compress", { "type": "upload", "endpoint": "http://example.com" }]
  ]
}
```

As you may be able to imagine, the **simple** and **detailed** definitions are
simply shortcuts for a **sequence** definition of only one element.

## Input Artifacts

When using post-processors, the input artifact (coming from a builder or
another post-processor) is discarded by default after the post-processor runs.
This is because generally, you don't want the intermediary artifacts on the way
to the final artifact created.

In some cases, however, you may want to keep the intermediary artifacts. You
can tell Packer to keep these artifacts by setting the `keep_input_artifact`
configuration to `true`. An example is shown below:

```json
{
  "post-processors": [
    {
      "type": "compress",
      "keep_input_artifact": true
    }
  ]
}
```

This setting will only keep the input artifact to _that specific_
post-processor. If you're specifying a sequence of post-processors, then all
intermediaries are discarded by default except for the input artifacts to
post-processors that explicitly state to keep the input artifact.

-> **Note:** The intuitive reader may be wondering what happens if multiple
post-processors are specified (not in a sequence). Does Packer require the
configuration to keep the input artifact on all the post-processors? The answer
is no, of course not. Packer is smart enough to figure out that at least one
post-processor requested that the input be kept, so it will keep it around.

## Run on Specific Builds

You can use the `only` or `except` fields to run a post-processor only with
specific builds. These two fields do what you expect: `only` will only run the
post-processor on the specified builds and `except` will run the post-processor
on anything other than the specified builds. A sequence of post-processors will
execute until a skipped post-processor.

An example of `only` being used is shown below, but the usage of `except` is
effectively the same. `only` and `except` can only be specified on "detailed"
fields. If you have a sequence of post-processors to run, `only` and `except`
will affect that post-processor and stop the sequence.

The `-except` option can specifically skip a named post processor. The `-only`
option _ignores_ post-processors.

```json
([
  {
    // can be skipped when running `packer build -except vbox`
    "name": "vbox",
    "type": "vagrant",
    "only": ["virtualbox-iso"]
  },
  {
    "type": "compress" // will only be executed when vbox is
  }
],
[
  "compress", // will run even if vbox is skipped, from the same start as vbox.
  {
    "type": "upload",
    "endpoint": "http://example.com"
  }
  // this list of post processors will execute
  // using build, not another post-processor.
])
```

The values within `only` or `except` are _build names_, not builder types. If
you recall, build names by default are just their builder type, but if you
specify a custom `name` parameter, then you should use that as the value
instead of the type.