# How to Delete a Stopped Container with the Apple Container Tool > Easily delete stopped containers using the Apple Container tool. Learn the simple container rm command to clean up your stopped containers efficiently. Find out how now. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-28 --- **Use `container rm ` after stopping the container, or `container rm -f ` to force-remove a running container in one step.** The `apple/container` repository provides an OCI-compatible runtime that manages container lifecycles through a convenient CLI. Understanding how to properly delete stopped containers is essential for resource cleanup and automated build scripts. This guide covers the exact commands and source implementation details for safely removing containers. ## Prerequisites for Deleting a Container Before deletion, a container must be in a stopped state. The Apple Container tool enforces this lifecycle to prevent accidental data loss or orphaned processes. ### Stopping vs. Force-Removing You have two primary paths for deletion: - **Graceful removal**: Stop the container first, then delete it using separate commands - **Force removal**: Use the `-f` flag to combine stopping and deletion into a single atomic operation Both approaches are implemented in [`Sources/ContainerCommands/ContainerCommands.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/ContainerCommands.swift), which parses the `rm` arguments and handles the runtime deletion logic. ## Step-by-Step: Delete a Stopped Container Follow this sequence to safely remove a container that is no longer running: 1. **Verify the container exists** by listing all containers including stopped ones: ```bash container list --all ``` 2. **Stop the container** if it is still running: ```bash container stop buildkit ``` 3. **Delete the stopped container**: ```bash container rm buildkit ``` This pattern matches the lifecycle model used throughout the repository, particularly in automated scripts that require explicit state management before cleanup. ## Force Removal with the `-f` Flag When you need to delete a container without a separate stop step, the `-f` (force) flag tells the tool to stop the container if it is still running and then delete it in a single operation. According to the build documentation in [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md) (lines 136-140), this is the canonical approach for removing the `buildkit` container before rebuilding a custom builder image: ```bash container rm -f buildkit ``` The `-f` flag is particularly useful in CI/CD pipelines and build scripts where you want to ensure a clean state without checking the current container status first. ## Implementation Details in the Source Code The container deletion logic is distributed across several key files in the repository: - **[`Sources/ContainerCommands/ContainerCommands.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/ContainerCommands.swift)**: Contains the actual implementation of the `rm` sub-command, including argument parsing and the runtime call to delete the container - **[`scripts/ensure-container-stopped.sh`](https://github.com/apple/container/blob/main/scripts/ensure-container-stopped.sh)**: A helper script that checks whether container services are still running before proceeding with cleanup operations - **`Sources/ContainerCommands/ContainerCommandsTests/`**: The test suite that guarantees `rm` behaves correctly when the target is stopped or when the `-f` flag is used These components work together to ensure that `container rm` follows OCI runtime standards while providing Apple-specific optimizations for the deletion workflow. ## Summary - **Always stop first**: Use `container stop ` before `container rm ` for graceful deletion - **Force when needed**: Add `-f` to remove running containers without manual stopping, as shown in [`BUILDING.md`](https://github.com/apple/container/blob/main/BUILDING.md) - **Verify deletion**: Run `container list --all` to confirm the container no longer appears - **Source implementation**: The `rm` logic lives in [`Sources/ContainerCommands/ContainerCommands.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/ContainerCommands.swift) ## Frequently Asked Questions ### Can I delete a running container without stopping it first? Yes, by using the `-f` flag with the `rm` command. According to the source code in [`Sources/ContainerCommands/ContainerCommands.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/ContainerCommands.swift), the `-f` flag instructs the runtime to stop the container if it is running and immediately delete it in one operation. This eliminates the need for a separate `container stop` command. ### What is the difference between `container stop` and `container kill`? Both commands halt a running container, but `container stop` attempts a graceful shutdown by sending the standard termination signal, while `container kill` forces immediate termination. You can use either before `container rm`, or rely on `container rm -f` which handles the stopping automatically. ### Where can I find the implementation of the `rm` command? The `rm` sub-command is implemented in [`Sources/ContainerCommands/ContainerCommands.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/ContainerCommands.swift). This file contains the Swift code that parses command-line arguments, interfaces with the OCI runtime, and executes the deletion logic. The accompanying test suite in `Sources/ContainerCommands/ContainerCommandsTests/` validates the behavior for both stopped and running containers. ### How do I verify a container has been deleted? Run `container list --all` to display all containers including stopped ones. If the deletion was successful, the container name or ID will no longer appear in the output. The [`scripts/ensure-container-stopped.sh`](https://github.com/apple/container/blob/main/scripts/ensure-container-stopped.sh) helper script demonstrates this verification pattern by checking for running services before proceeding with dependent operations.