# How to Run an Ubuntu Container Using Apple Container > Easily run Ubuntu containers on macOS with Apple Container. This guide shows you how to use the container CLI to launch standard Ubuntu images and leverage lightweight VMs. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-28 --- **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`](https://github.com/apple/container/blob/main/docs/command-reference.md) and [`README.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/README.md), the following command launches the `container-apiserver` and helper services that manage VMs, networking, and images: ```bash 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: ```bash container image pull ubuntu:latest --arch arm64 ``` To pull for Intel-based containers: ```bash 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: ```bash 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: ```bash 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: ```bash 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`](https://github.com/apple/container/blob/main/docs/command-reference.md). ### Limit CPU and Memory Prevent resource oversubscription by setting explicit constraints: ```bash 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: ```bash 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: ```bash 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: ```bash container stop ``` ## Summary - Apple Container utilizes lightweight VMs to run Linux containers on macOS, as explained in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md) and [`docs/start-here.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.