# How to Install and Manage Custom Linux Kernels with Apple Container > Learn how to install and manage custom Linux kernels in Apple Container. Easily set kernels globally, per-container, or persistently with simple commands and configuration edits. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-12 --- **You can install custom Linux kernels in Apple Container by using the `container system kernel set` command for global installation, the `-k` flag for per-container overrides, or by editing the `[kernel]` section in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) for persistent configuration.** Apple Container runs containers inside lightweight virtual machines that require a Linux kernel with specific virtualization features. While the CLI can automatically download a recommended Kata Containers kernel, you can also supply your own kernel binary or archive to meet specific hardware or workload requirements. The kernel configuration is managed through the `KernelConfig` type defined in the runtime configuration. ## Understanding Kernel Configuration The kernel handling logic in Apple Container is driven by the **`KernelConfig`** type defined in the runtime configuration file ([`config.toml`](https://github.com/apple/container/blob/main/config.toml)). This configuration specifies how the runtime discovers and loads kernel binaries for the virtual machines. The `KernelConfig` struct contains two critical fields: - **`binaryPath`** – The path inside the downloaded archive that points to the actual kernel binary. - **`url`** – The remote URL of the archive to download when no kernel is present locally. Default values for these fields are defined in **[`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift)** within the repository. When you install a custom kernel, you are essentially updating these configuration values to point to your preferred binary. ## Installing Custom Kernels Apple Container provides three distinct methods for controlling kernel installation and selection. ### Install from a Local Binary To install a kernel binary you have compiled locally, use the `--binary` flag with the `container system kernel set` command. This is useful when you have built a custom kernel with specific `CONFIG_KVM` or `CONFIG_VIRTIO_*` options enabled. ```bash container system kernel set \ --binary /usr/local/src/linux/arch/arm64/boot/vmlinux \ --force ``` The `--force` flag overwrites any existing kernel with the same name. ### Install from an Archive or Remote URL You can also install kernels packaged in archives (tarballs or zip files) either locally or downloaded from a remote URL. The **`binaryPath`** configuration must correctly point to the kernel location within the archive structure. ```bash # Install from a remote Kata Containers release container system kernel set \ --tar https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst \ --force # Install from a local archive container system kernel set \ --tar /path/to/kernel-archive.tar ``` ### Use the Recommended Kata Kernel To revert to or install the officially supported Kata Containers kernel that Apple Container recommends, use the `--recommended` flag: ```bash container system kernel set --recommended ``` This downloads the default kernel archive configured in the system settings. ## Managing Kernels for Specific Containers You can manage kernel selection at either the global system level or for individual container runs. ### Per-Container Kernel Overrides To use a custom kernel for a single container execution without changing the system-wide configuration, use the `-k` or `--kernel` flag with the `container run` command: ```bash container run \ -k /opt/kernels/vmlinux-custom \ -it alpine:latest sh ``` This override applies only to that specific container instance and does not modify the persistent configuration. ### Persistent Configuration via config.toml For environments like CI pipelines where you need consistent kernel settings, edit the **[`config.toml`](https://github.com/apple/container/blob/main/config.toml)** file directly to persist custom kernel paths: ```toml [kernel] binaryPath = "/opt/kernels/vmlinux-custom" url = "file:///opt/kernels/custom-kernel.tar.zst" ``` After modifying the configuration, restart the Apple Container system services to apply the changes: ```bash container system restart ``` Alternatively, you can stop and start the services separately: ```bash container system stop && container system start ``` ## Verifying Kernel Installation After installing a custom kernel, verify the current configuration using the `container system property list` command: ```bash container system property list | grep kernel ``` For detailed JSON output showing both the `binaryPath` and `url` values: ```bash container system property list --format json | jq '.kernel' ``` You should see `binaryPath` pointing to your installed file and `url` showing either the original download URL or a `file://` scheme for local installations. ## Summary - Apple Container uses the **`KernelConfig`** type in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) to manage kernel paths and download URLs, with defaults defined in [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift). - **Install custom kernels globally** using `container system kernel set` with `--binary` for local files or `--tar` for archives. - **Override kernels per-container** using the `-k` flag with `container run` for temporary testing. - **Persist configuration** by editing the `[kernel]` section in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) and restarting the system services. - **Verify installation** with `container system property list` to confirm `binaryPath` and `url` values. ## Frequently Asked Questions ### What kernel configuration options are required for Apple Container? Your custom Linux kernel must include specific virtualization features to support Apple Container's lightweight virtual machines. Required options include **`CONFIG_KVM`** for KVM virtualization support and **`CONFIG_VIRTIO_*`** options for VirtIO device drivers. Without these enabled, the kernel will not function correctly within the Apple Container runtime. ### How do I check which kernel Apple Container is currently using? Run the command `container system property list` and filter for kernel entries, or use the JSON output format with `jq` to inspect the kernel object specifically. This displays the current `binaryPath` (location of the kernel binary) and `url` (source of the kernel), allowing you to verify whether the system is using a custom installation or the default recommended kernel. ### What is the difference between using `--binary` and `--tar` with the kernel set command? The `--binary` flag installs a single, uncompressed kernel file (such as a `vmlinux` binary) directly into the system. The `--tar` flag accepts either a local archive path or a remote URL, downloads the archive if necessary, and extracts the kernel binary from within it using the path specified in the `binaryPath` configuration. Use `--binary` for standalone kernel files and `--tar` when the kernel is packaged in a compressed archive. ### Can I use different kernels for different containers without changing the system default? Yes. Use the `-k` or `--kernel` flag with the `container run` command to specify a custom kernel path for a single container execution. This per-container override does not modify the global configuration stored in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) or affect other running containers, making it ideal for testing specific kernel versions against individual workloads.