Articles

Packer Debug Mode: Step Through Builds Interactively (2026)

April 18, 2026 14 min read

Packer’s debug mode is less about seeing what Packer is doing and more about telling it what to do while it’s doing it, turning a black box into an interactive shell.

Let’s watch a Packer build in debug mode. Imagine you have a template.pkr.hcl file like this:

source "amazon-ebs" "example" {

  ami_name      = "packer-debug-example-{{timestamp}}"

  instance_type = "t2.micro"
  region        = "us-east-1"
  ssh_username  = "ec2-user"
  source_ami_filter {
    filters = {
      name = "amzn2-ami-hvm-*-x86_64-gp2"
    }
    most_recent = true
  }
}

build {
  sources = ["source.amazon-ebs.example"]

  provisioner "shell" {
    inline = [
      "echo 'Hello, Packer Debug!'",
      "sudo yum update -y",
      "echo 'Update complete.'"
    ]
  }
}

Now, you want to poke around during the yum update step. You’d run:

packer build -debug template.pkr.hcl

Packer will start up, provision an EC2 instance, and then, before executing the first provisioner "shell" command, it will drop you into an interactive shell on that instance. You’ll see output like this:

...
amazon-ebs: Waiting for SSH to become available...
amazon-ebs: Machine is booted! Waiting for winrm or ssh to come online.
amazon-ebs: SSH hung after 3 attempts. Retrying...
amazon-ebs: Trying to connect to SSH...
amazon-ebs: Connected to SSH!
amazon-ebs: Starting provisioner: shell
amazon-ebs: Provisioning with shell script:
amazon-ebs:
amazon-ebs: echo 'Hello, Packer Debug!'
amazon-ebs: sudo yum update -y
amazon-ebs: echo 'Update complete.'
amazon-ebs:
==> amazon-ebs: Provisioning with shell script:
    echo 'Hello, Packer Debug!'
    sudo yum update -y
    echo 'Update complete.'

==> amazon-ebs: [DEBUG] Waiting for command to finish: echo 'Hello, Packer Debug!'
==> amazon-ebs: [DEBUG] Standard output:
==> amazon-ebs: [DEBUG] Hello, Packer Debug!
==> amazon-ebs: [DEBUG] Standard error:
==> amazon-ebs: [DEBUG] Command finished.
==> amazon-ebs: [DEBUG] Waiting for command to finish: sudo yum update -y
==> amazon-ebs: [DEBUG] Standard output:
==> amazon-ebs: [DEBUG] Standard error:
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from 172.31.10.20
==> amazon-ebs: [DEBUG]
==> amazon-ebs: [DEBUG] Last login: Tue Sep 19 10:00:00 2023 from

Want structured learning?

Take the full Packer course →