How to Safely Remove Containers and Clean Up Resources in apple/container

To safely remove containers and clean up resources in apple/container, execute a layered teardown workflow: stop running containers and launch-d services with container stop or container system stop, delete objects using container delete, prune stopped containers and images, remove persistent volumes, and optionally run scripts/uninstall-container.sh to purge the CLI and user data.

The apple/container repository provides a macOS-native container runtime that orchestrates container lifecycle through launch-d services and persistent storage. To safely remove containers and clean up resources, you must deregister system services, reclaim disk space from dangling images, and purge volume data to prevent orphaned resources. Understanding the proper sequence ensures no background agents remain active and all on-disk artifacts are reclaimed.

Stop Running Containers and Background Services

The container stop command sends a graceful shutdown signal to each container process, falling back to SIGKILL after a timeout if the process does not terminate. For a complete system halt that deregisters all launch-d services introduced by the daemon, use container system stop instead. This command ensures that no background XPC services remain active, preventing orphaned processes that could interfere with subsequent cleanup.

The helper script scripts/ensure-container-stopped.sh implements the same teardown logic for underlying launch-d domains, which the system invokes internally during shutdown operations. These behaviors are documented in docs/command-reference.md and utilize the XPC communication layer defined in Sources/ContainerXPC/.

# Stop all running containers gracefully

container stop --all

# Alternative: Stop the entire container system and deregister launch-d services

container system stop

Delete Container Objects

Use container delete (or its short form container rm) to remove one or more container objects. The command respects the --all flag to wipe the entire container set. While the --force flag will delete running containers immediately, it is safer to stop them first to ensure proper cleanup of resources managed by Sources/ContainerPlugin/.

# Delete specific containers by name or ID

container delete mywebapp db

# Delete all containers, including running ones (use with caution)

container delete --force --all

Prune Stopped Containers and Dangling Images

The container prune command removes all stopped containers in a single operation, reporting the amount of disk space reclaimed. To clean up unused images, run container image prune, which clears untagged images. Adding the -a flag removes any image not currently referenced by a container, aggressively freeing storage according to the docs/command-reference.md specification.

# Remove all stopped containers

container prune

# Remove untagged images

container image prune

# Remove all images not referenced by containers

container image prune -a

Clean Up Persistent Volumes and Anonymous Mounts

Volumes survive container deletion unless explicitly removed. Run container volume delete <name> to remove specific volumes, or use container volume delete --all to purge the entire volume set. Note that anonymous volumes created by -v or --mount flags must also be deleted manually, as they persist in the filesystem under Sources/ContainerPlugin/ management.

# Delete a specific volume

container volume delete mydata

# Delete all volumes, including anonymous ones

container volume delete --all

Uninstall the CLI and Remove User Data

To completely remove the container binary and its helpers, execute the provided scripts/uninstall-container.sh script. The script first checks that no services are running via scripts/ensure-container-stopped.sh, then removes installed files via pkgutil. Supply the -d flag to additionally wipe the user data directory located at ~/Library/Application Support/com.apple.container.

# Uninstall the CLI and remove user data

sudo ./scripts/uninstall-container.sh -d

Summary

• Stop services first using container stop --all or container system stop to deregister launch-d agents and prevent orphaned processes.
• Delete containers with container delete or container rm, preferring to stop containers before deletion rather than using --force.
• Prune resources using container prune for stopped containers and container image prune -a for unused images.
• Remove volumes explicitly with container volume delete --all to reclaim filesystem space from persistent and anonymous mounts.
• Uninstall completely by running scripts/uninstall-container.sh -d to eliminate binaries via pkgutil and user data from the Library directory.

Frequently Asked Questions

What is the difference between container stop and container system stop?

The container stop command targets individual containers, sending a graceful termination signal that escalates to SIGKILL after a timeout. In contrast, container system stop deregisters all launch-d services introduced by the container daemon, effectively halting the entire runtime environment and ensuring no background XPC services managed by Sources/ContainerXPC/ remain active.

How do I remove all unused volumes in apple/container?

Run container volume delete --all to purge every volume managed by the system, including anonymous volumes created via -v or --mount flags. Unlike container deletion, this command must be executed explicitly to prevent accidental data loss, as volumes persist independently of container lifecycle in the filesystem managed by Sources/ContainerPlugin/.

Will uninstalling the container CLI delete my container data?

Running scripts/uninstall-container.sh without flags removes only the binaries and installed files via pkgutil, leaving user data intact. To completely remove container data including the ~/Library/Application Support/com.apple.container directory, you must execute the script with the -d flag, which wipes all persistent state and cached artifacts.

Why should I avoid using --force when deleting containers?

While container delete --force immediately terminates running containers, it bypasses the graceful shutdown sequence implemented in Sources/ContainerPlugin/, potentially leaving orphaned volume mounts or network configurations. Stopping containers first ensures proper resource cleanup and prevents dangling references that could interfere with subsequent cleanup operations.

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