How to Delete a Stopped Container with the Apple Container Tool

Use container rm <name-or-id> after stopping the container, or container rm -f <name-or-id> 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, 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:

container list --all

2. Stop the container if it is still running:

container stop buildkit

3. Delete the stopped container:

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 (lines 136-140), this is the canonical approach for removing the buildkit container before rebuilding a custom builder image:

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: 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: 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 <name-or-id> before container rm <name-or-id> for graceful deletion
• Force when needed: Add -f to remove running containers without manual stopping, as shown in 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

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, 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. 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 helper script demonstrates this verification pattern by checking for running services before proceeding with dependent operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}