# How to Force Rebuild Docker Images in act: Complete Guide

> Learn how to force rebuild Docker images in act with the --rebuild flag. Skip unnecessary builds by reusing cached images for faster workflows.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Use the `--rebuild` flag to force act to rebuild Docker images for local actions, or set `--rebuild=false` to reuse cached images and skip unnecessary builds.**

The `nektos/act` CLI tool executes GitHub Actions workflows locally using Docker containers. When you need to **force rebuild Docker images in act**—such as after modifying a local action's Dockerfile or source code—you must understand how the tool handles image caching to ensure your changes take effect.

## Understanding the `--rebuild` Flag

By default, act rebuilds Docker images for local actions on every run. The `--rebuild` boolean flag in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) defaults to `true`, meaning the tool automatically discards cached images and rebuilds them unless you explicitly disable this behavior. To reuse existing images and speed up execution, you must pass `--rebuild=false`.

This design ensures that local action changes are always picked up during development, while CI environments or repetitive testing can opt into caching for performance.

## How Force Rebuild Works Under the Hood

The rebuild logic flows through several components in the `nektos/act` codebase, from CLI parsing to Docker execution.

### CLI Flag Definition

In [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) at line 86, the `--rebuild` flag is defined as a Boolean with a default value of `true`:

```go
// Simplified representation of the flag definition
cmd.PersistentFlags().BoolP("rebuild", "", true, "rebuild local action docker images")

```

This means the flag is effectively always present, defaulting to forced rebuild behavior when omitted from the command line.

### Runner Configuration Propagation

The flag value propagates through the input struct and into `RunnerConfig` at line 612 of [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go), specifically mapping to the `ForceRebuild` field:

```go
// Configuration mapping
runnerConfig.ForceRebuild = input.rebuild

```

The `RunnerConfig` struct in [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go) at line 33 stores this setting, making it available to the execution engine.

### Image Rebuild Decision Logic

When act prepares to execute a Docker-based local action, [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go) at line 287 evaluates whether to rebuild. The code checks two conditions: whether the required architecture is already present in the cache, **or** whether `ForceRebuild` is `true`. If either condition is met, act triggers a rebuild:

```go
// Conceptual representation of the check
if needsRebuild || rc.Config.ForceRebuild {
    // Proceed to docker build
}

```

### Docker Build Execution

The actual rebuild occurs in [`pkg/runner/step_docker.go`](https://github.com/nektos/act/blob/main/pkg/runner/step_docker.go), which invokes the Docker daemon with the appropriate `docker build` command. This step only uses the cached image context when `ForceRebuild` is explicitly set to `false`.

## Practical Usage Examples

### Forcing a Fresh Build

To ensure all local action images are rebuilt with your latest changes, run act with the default rebuild behavior:

```bash
act --rebuild

```

Since the flag defaults to `true`, you can also simply run `act` without arguments to achieve the same result.

### Reusing Cached Images

To skip rebuilding and use existing Docker images for faster execution:

```bash
act --rebuild=false

```

This is useful when running workflows repeatedly without modifying local actions.

### Integration with CI Scripts

Add the flag to shell scripts or Makefiles for consistent behavior across environments:

```bash
#!/usr/bin/env bash

# Force fresh builds in CI environment

act --rebuild --job test

```

Or in a Makefile:

```make
.PHONY: local-ci
local-ci:
	act --rebuild=false --job build

```

## Summary

- **Default behavior**: Act rebuilds Docker images on every run (`--rebuild` defaults to `true`).
- **Disable rebuilds**: Use `--rebuild=false` to cache and reuse local action images.
- **Source flow**: The flag travels from [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) → `RunnerConfig.ForceRebuild` in [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go) → rebuild logic in [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go) → execution in [`pkg/runner/step_docker.go`](https://github.com/nektos/act/blob/main/pkg/runner/step_docker.go).
- **Rebuild trigger**: Occurs when `ForceRebuild` is `true` or when the required architecture is missing from the cache.

## Frequently Asked Questions

### What is the default value of the `--rebuild` flag in act?

The `--rebuild` flag defaults to `true` as defined in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go). This means act automatically rebuilds Docker images for local actions on every run unless you explicitly pass `--rebuild=false`.

### How do I skip Docker image rebuilding to speed up local testing?

Pass `--rebuild=false` to the act command. This tells the runner to reuse any existing cached images for local actions, significantly reducing execution time when you have not modified the action code or Dockerfile.

### Does `--rebuild` affect remote actions or only local actions?

The `--rebuild` flag specifically controls Docker image building for **local actions** (actions defined in your repository). Remote actions pulled from external repositories are not affected by this flag, as they use pre-built images or their own build processes.

### Where is the force rebuild logic implemented in the act source code?

The logic spans four key files: [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) defines the flag and passes it to the runner; [`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go) stores it in `RunnerConfig.ForceRebuild`; [`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go) at line 287 checks the flag to decide whether to rebuild; and [`pkg/runner/step_docker.go`](https://github.com/nektos/act/blob/main/pkg/runner/step_docker.go) executes the actual Docker build command.