How to Run an Ubuntu Container Using Apple Container

Apple Container runs Linux containers on macOS by launching a lightweight virtual machine for each container, allowing you to execute standard Ubuntu images directly using the container CLI.

Apple Container is an open-source project from the apple/container repository that enables Linux container execution on macOS through lightweight virtualization. You can run Ubuntu containers using standard OCI images without complex configuration. This guide walks through the exact commands and flags documented in docs/command-reference.md and README.md to get an Ubuntu shell running in seconds.

Start the Container System

Before running any image, you must initialize the Apple Container runtime. According to README.md, the following command launches the container-apiserver and helper services that manage VMs, networking, and images:

container system start

Pull the Ubuntu Image (Optional)

While Apple Container automatically pulls images on first use, explicit pulling allows you to verify architecture compatibility and view download progress. The --arch flag selects the image variant, defaulting to your host architecture when omitted.

To pull for Apple Silicon:

container image pull ubuntu:latest --arch arm64

To pull for Intel-based containers:

container image pull ubuntu:latest --arch amd64

Run Ubuntu Interactively

The container run command accepts standard Docker-style flags to launch containers. The most common workflow involves starting an interactive shell inside the Ubuntu image.

Launch an Interactive Shell

The following command allocates a pseudo-tty and keeps stdin open, giving you a fully functional bash environment:

container run -it ubuntu:latest /bin/bash

The -i flag keeps stdin open, while -t allocates a pseudo-tty. This combination connects your terminal directly to the Ubuntu container process.

Cross-Architecture Execution

To run an x86-64 Ubuntu container on Apple Silicon hardware, explicitly specify the architecture before the image name:

container run -it --arch amd64 ubuntu:latest /bin/bash

This enables running Intel-based containers on ARM64 hosts without additional configuration.

Run Detached with Port Mapping

For background services, omit the interactive flags and use -d for detached mode:

container run -d -p 8080:80 ubuntu:latest

Configure Runtime Options

The container run command supports fine-grained control over container execution through resource limits, networking, and process management flags detailed in docs/command-reference.md.

Limit CPU and Memory

Prevent resource oversubscription by setting explicit constraints:

container run -it --cpus 2 --memory 4G ubuntu:latest /bin/bash

The --cpus flag limits processor cores, while --memory restricts RAM usage.

Attach to Custom Networks

Create isolated networks and assign specific MAC addresses:

container network create mynet
container run -it --network mynet,mac=02:42:ac:11:00:02 ubuntu:latest /bin/bash

Enable Init Process

For proper signal handling and zombie process reaping, add the --init flag:

container run -it --init ubuntu:latest /bin/bash

This runs an init helper inside the container that forwards signals correctly, essential for long-running services.

Stop and Clean Up

When you exit an interactive shell using exit or Ctrl+D, the container stops automatically if you passed the --rm flag during creation. Otherwise, stop containers manually using their ID:

container stop <container-id>

Summary

• Apple Container utilizes lightweight VMs to run Linux containers on macOS, as explained in docs/technical-overview.md and docs/start-here.md.
• Initialize the system with container system start before executing images.
• Use container run -it ubuntu:latest /bin/bash to start an interactive Ubuntu shell.
• Specify --arch amd64 or --arch arm64 to select image variants for different CPU architectures.
• Resource limits (--cpus, --memory), custom networking (--network), and init processes (--init) provide production-grade control over container execution.

Frequently Asked Questions

How does Apple Container execute Linux containers on macOS?

According to docs/technical-overview.md, Apple Container launches a lightweight virtual machine for each container. This architecture allows the runtime to execute standard Linux OCI images natively on macOS without requiring a full Linux installation or Docker Desktop.

Can I run Ubuntu containers for a different CPU architecture than my Mac?

Yes. The CLI supports the --arch flag to select image variants. Use --arch amd64 to run Intel-based Ubuntu containers on Apple Silicon Macs, or --arch arm64 for ARM64 variants. If omitted, the CLI defaults to the host architecture as documented in docs/command-reference.md.

Do I need to manually pull images before running them?

No, pulling is optional. Apple Container automatically pulls the image the first time it is referenced. However, explicit pulling with container image pull allows you to verify the architecture and view download progress before execution, as noted in docs/how-to.md.

How do I enable proper signal handling in Ubuntu containers?

Pass the --init flag to container run. This runs an init helper inside the container that forwards signals and reaps zombie processes, which is essential for long-running services that must handle process signals correctly.

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