# How to Run Custom Linux Distributions on Mac with the Container Tool

> Run custom Linux distributions on Mac using apple/container. Create a persistent Linux VM with systemd and easily share your macOS home directory for a seamless workflow.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-03

---

**You can run custom Linux distributions on Mac by building an OCI image with an init system like `systemd`, registering it via `container machine create`, and launching it with `container machine run`, which provides a persistent Linux VM that automatically shares your macOS home directory.**

The `container` tool (formerly Docker for Apple Silicon) from the Apple container repository enables developers to run custom Linux distributions on macOS using lightweight virtual machines backed by OCI-compatible images. Unlike traditional containers, a **container machine** runs a full Linux init system such as `systemd` inside a hypervisor-based VM, giving you a complete Linux environment while maintaining seamless integration with macOS networking and file systems. This architecture allows you to run any distribution—Alpine, Ubuntu, Fedora, or Debian—directly on Apple Silicon or Intel Macs.

## Architecture of Container Machines

The `container` tool leverages Apple's hypervisor framework to launch sandboxed Linux VMs through the `vminitd` helper, with orchestration logic implemented in Swift sources such as [`Sources/ContainerXPC/XPCServer.swift`](https://github.com/apple/container/blob/main/Sources/ContainerXPC/XPCServer.swift). Each container machine boots a minimal Linux kernel bundled with the tool and mounts an **OCI rootfs** image as its filesystem, requiring an init binary at `/sbin/init` to manage the system. When you create a machine, the tool writes a configuration file to `~/.config/container/machines/<name>.toml` that stores the image reference and resource settings, while automatically bind-mounting your macOS `$HOME` directory to `/home/<username>` inside the VM.

## Building a Custom Linux Distribution Image

To run your preferred distribution, you must first create an OCI image containing a compatible init system. Below is a minimal Dockerfile for Ubuntu 24.04 that installs `systemd` and prepares the image for use as a container machine, adapted from the [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md) documentation.

```dockerfile

# Dockerfile – custom Ubuntu container machine

FROM ubuntu:24.04

ENV container container

RUN apt-get update && \
    apt-get install -y \
      dbus systemd openssh-server net-tools iproute2 iputils-ping \
      curl wget vim-tiny man sudo && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* && \
    yes | unminimize

RUN > /etc/machine-id && \
    > /var/lib/dbus/machine-id

RUN systemctl set-default multi-user.target && \
    systemctl mask \
      dev-hugepages.mount \
      sys-fs-fuse-connections.mount \
      systemd-update-utmp.service \
      systemd-tmpfiles-setup.service && \
    systemctl disable networkd-dispatcher.service

RUN sed -i -e 's/^AcceptEnv LANG LC_*/#AcceptEnv LANG LC_*/' /etc/ssh/sshd_config

```

Save this as `Dockerfile` in your project directory, then build the image using the `container` CLI. The build process runs inside a lightweight builder VM managed by the tool, with progress UI handled by `Sources/TerminalProgress/`.

```bash
container build -t local/ubuntu-machine:latest .

```

## Creating and Running Container Machines

Once the image is built, register it as a persistent virtual machine using `container machine create`. This command records the image reference in the machine configuration file and prepares the VM for execution.

```bash
container machine create local/ubuntu-machine:latest --name ubuntu-dev

```

Start an interactive shell inside the Linux VM using `container machine run`. Your macOS username and home directory are immediately available inside the VM, allowing you to edit files on macOS using native applications and compile or run them inside Linux.

```bash

# Launch an interactive shell

container machine run -n ubuntu-dev

# Execute a single command

container machine run -n ubuntu-dev uname -a

```

The integration preserves your working directory context when transitioning between macOS and the Linux environment, as documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md).

## Resource Configuration and Advanced Options

You can adjust CPU and memory allocation for existing machines using the `container machine set` command. These changes take effect after the next stop and start cycle.

```bash
container machine set -n ubuntu-dev cpus=4 memory=8G
container machine stop ubuntu-dev
container machine run -n ubuntu-dev

```

For specialized workloads requiring hardware virtualization support inside the VM (such as running Docker within your Linux distribution), provide a custom kernel compiled with `CONFIG_KVM=y` and enable nested virtualization during machine creation.

```bash
container machine create \
    --virtualization \
    --kernel /path/to/vmlinux-kvm \
    --name kvm-dev \
    local/ubuntu-machine:latest

```

This configuration is detailed in the "Nested virtualization and custom kernels" section of [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md).

## Summary

- **Container machines** are persistent Linux VMs that run OCI images with init systems like `systemd` on macOS using Apple's hypervisor framework.
- **Build** custom distribution images with standard Dockerfiles using `container build`, ensuring the image includes `/sbin/init` and is defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) as compatible.
- **Register** machines with `container machine create`, which stores configuration in `~/.config/container/machines/<name>.toml`.
- **Launch** environments with `container machine run`, which automatically shares your macOS `$HOME` directory with the Linux VM.
- **Configure** resources and custom kernels using `container machine set` and creation flags for specialized hardware requirements.

## Frequently Asked Questions

### What Linux distributions are supported by the container tool?

You can run any Linux distribution that supports the `systemd` init system or provides an alternative init binary at `/sbin/init`. The repository includes examples for Ubuntu, Debian, Fedora, and Alpine in `examples/container-machine-vscode/`. As long as you can build an OCI-compatible image containing an init system, the `container` tool can boot it as a container machine.

### Do I need Docker Desktop installed to use container?

No. The `container` tool is a standalone Swift package defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) that includes its own container engine and build system. It uses its own storage for images and machines, independent of Docker Desktop, though it uses standard OCI image formats and Dockerfile syntax compatible with Docker.

### How does file sharing work between macOS and the Linux VM?

The `container` tool automatically bind-mounts your macOS `$HOME` directory into the VM at `/home/<username>`, allowing seamless access to files without manual syncing or copying. This integration is handled by the VM orchestration layer in `Sources/ContainerXPC/` and persists across reboots of the container machine.

### Can I run graphical Linux applications using container machines?

While the primary use case targets development environments and command-line tools, you can run graphical applications by forwarding X11 or using other display protocols, as the VM includes standard networking and file system access. The VS Code integration example in [`examples/container-machine-vscode/README.md`](https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md) demonstrates how to use the container machine as a full-featured remote development environment.