# How to Remove Unused Container Images and Objects Using Container Prune

> Master container prune commands for efficient cleanup. Learn to remove unused images, stopped containers, and dangling objects to optimize your apple/container setup.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Use `container prune` to delete stopped containers, `container image prune` to remove dangling or unused images, and `container network prune` or `container volume prune` to clean up networks and volumes no longer attached to containers.**

The `container` CLI from the apple/container repository provides a family of prune commands designed to reclaim disk space by removing unused resources. These commands follow a consistent pattern across containers, images, networks, and volumes, making system maintenance straightforward and safe for automation scripts.

## Understanding the Container Prune Command Family

The prune sub-commands target specific resource types that accumulate during development. Each command operates without interactive prompts, allowing them to run safely in CI/CD pipelines.

- **`container prune`**: Removes stopped containers from the system.
- **`container image prune`**: Deletes dangling images (and optionally all unused images with the `-a` flag).
- **`container network prune`**: Eliminates networks that have no containers currently attached.
- **`container volume prune`**: Cleans up data volumes that are not mounted by any running or stopped container.

## How Container Prune Works Under the Hood

According to the apple/container source code, the prune logic follows a consistent implementation pattern across resource types, with each command residing in its own Swift file under the ContainerCommands module.

### Container Prune Implementation

In [`Sources/ContainerCommands/Container/ContainerPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerPrune.swift), the command filters the container list to include only stopped instances using `ContainerListFilters(status: .stopped)` [source lines 35-40]. For each stopped container, the implementation retrieves disk usage statistics via `client.diskUsage`, then permanently deletes the container using `client.delete`. The command accumulates the total reclaimed bytes and outputs each pruned container ID followed by a summary log message [source lines 41-66].

### Image, Network, and Volume Prune

The same architectural pattern appears in companion files:
- **[`Sources/ContainerCommands/Image/ImagePrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImagePrune.swift)** – Handles dangling and unused image removal.
- **[`Sources/ContainerCommands/Network/NetworkPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Network/NetworkPrune.swift)** – Manages network cleanup logic.
- **[`Sources/ContainerCommands/Volume/VolumePrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Volume/VolumePrune.swift)** – Handles volume deletion.

All implementations share a minimal CLI surface with no extra flags beyond global options like `--debug` for verbose output, as documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) [source lines 17-27].

## Practical Examples for Cleaning Up Resources

Run these commands to reclaim disk space on your host system:

Remove all stopped containers:

```bash
container prune

```

Remove only dangling images (untagged layers not referenced by any container):

```bash
container image prune

```

Remove all unused images, including tagged ones no longer referenced by containers:

```bash
container image prune -a

```

Remove unused networks:

```bash
container network prune

```

Remove unused volumes:

```bash
container volume prune

```

Enable verbose logging with the global `--debug` flag to see detailed operation information during execution.

## Summary

- The **`container prune`**, **`container image prune`**, **`container network prune`**, and **`container volume prune`** commands provide targeted cleanup for specific resource types in the apple/container ecosystem.
- The implementation in [`Sources/ContainerCommands/Container/ContainerPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerPrune.swift) filters for stopped containers using `ContainerListFilters(status: .stopped)`, calculates disk usage via `client.diskUsage`, and performs deletion through `client.delete`.
- Use the `-a` flag with `container image prune` to remove all unused images, not just dangling (untagged) ones.
- All commands accept the `--debug` flag for verbose output and are designed with minimal CLI surfaces for safe use in automation scripts.

## Frequently Asked Questions

### What is the difference between container prune and container image prune?

`container prune` removes stopped containers, while `container image prune` removes images that are not referenced by any container. The container command affects runtime instances, whereas the image command targets the underlying filesystem layers stored on disk that consume storage space.

### Does container prune remove running containers?

No. According to the implementation in [`Sources/ContainerCommands/Container/ContainerPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerPrune.swift), the command specifically filters for containers with `status: .stopped` before deletion, ensuring that running containers remain untouched during the cleanup process.

### How do I remove all unused images including tagged ones?

Append the `-a` flag to the image prune command: `container image prune -a`. Without this flag, the command only removes dangling images (untagged layers), but with `-a` it removes all images not currently referenced by existing containers, regardless of whether they have tags.

### Where can I find the implementation of the prune commands?

The prune logic is implemented in the ContainerCommands source tree within the apple/container repository. Key files include [`Sources/ContainerCommands/Container/ContainerPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Container/ContainerPrune.swift) for containers, [`Sources/ContainerCommands/Image/ImagePrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Image/ImagePrune.swift) for images, [`Sources/ContainerCommands/Network/NetworkPrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Network/NetworkPrune.swift) for networks, and [`Sources/ContainerCommands/Volume/VolumePrune.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Volume/VolumePrune.swift) for volumes. User-facing documentation is available in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md).