# How to Upgrade Apple Container on macOS: Complete Command-Line Guide

> Upgrade Apple Container on macOS easily using commands. Follow this guide to stop the daemon and run the update script for the latest GitHub release.

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

---

**You can upgrade Apple Container by stopping the daemon with `container system stop` and running [`/usr/local/bin/update-container.sh`](https://github.com/apple/container/blob/main//usr/local/bin/update-container.sh) to automatically download and install the latest signed release from GitHub.**

Apple Container is a lightweight virtualization system distributed as a signed macOS installer package. Whether you are running the latest stable release or need to pin a specific version for testing, the upgrade process is handled entirely through the command line using helper scripts provided in the `apple/container` repository.

## Prerequisites for Upgrading Apple Container

Before initiating any upgrade, you must stop the active container service. The update script located at [`/usr/local/bin/update-container.sh`](https://github.com/apple/container/blob/main//usr/local/bin/update-container.sh) explicitly refuses to run while the `container` daemon is active to prevent data corruption or runtime conflicts.

Execute the following to halt the service:

```bash
container system stop

```

## Upgrading to the Latest Version

The recommended upgrade path uses the [`update-container.sh`](https://github.com/apple/container/blob/main/update-container.sh) helper script, which automates the retrieval and installation of the newest release.

### Step 1: Stop the Running Service

Ensure the daemon is completely stopped before proceeding:

```bash
container system stop

```

### Step 2: Run the Update Script

Execute the script without arguments to fetch the latest version from the GitHub releases page:

```bash
/usr/local/bin/update-container.sh

```

The script performs the following actions as implemented in [`scripts/update-container.sh`](https://github.com/apple/container/blob/main/scripts/update-container.sh):
- Queries the GitHub API at `https://api.github.com/repos/apple/container/releases/latest`
- Automatically selects the correct architecture (arm64 on Apple Silicon)
- Prioritizes signed `.pkg` assets, falling back to unsigned packages only with user confirmation
- Downloads the package using `curl` and installs it via the native macOS `installer` command

### Step 3: Verify the Installation

Confirm the upgrade succeeded by checking the version:

```bash
container --version

```

This displays both the CLI version and the underlying `container-apiserver` version.

## Upgrading to a Specific Version or Downgrading

For testing or compatibility requirements, you can install a specific tag or downgrade to an earlier release.

### Install a Specific Version

Use the `-v` flag to target a specific release tag:

```bash
/usr/local/bin/update-container.sh -v 0.4.1

```

### Force Reinstallation

If the script detects you are already running the target version, it skips installation. To bypass this guard and reinstall anyway, use the `-f` flag:

```bash
/usr/local/bin/update-container.sh -f

```

### Downgrade While Preserving Data

To downgrade, first uninstall the current version while keeping user data, then install the desired version:

```bash
/usr/local/bin/uninstall-container.sh -k
/usr/local/bin/update-container.sh -v 0.3.0

```

The `-k` flag preserves user data directories, allowing you to revert to an older version without losing existing containers or configurations.

## Understanding the Update Script Mechanics

The [`update-container.sh`](https://github.com/apple/container/blob/main/update-container.sh) script (source available at [`scripts/update-container.sh`](https://github.com/apple/container/blob/main/scripts/update-container.sh)) handles several critical functions that make it superior to manual package installation:

**Architecture Detection**: The script automatically identifies the host architecture and downloads the appropriate build, ensuring optimal performance on Apple Silicon (arm64) systems.

**Security Verification**: It checks for cryptographically signed `.pkg` assets first. If no signed package is available for the selected release, the script prompts for explicit confirmation before proceeding with an unsigned alternative.

**Entitlement Preservation**: By using macOS's native `installer` tool, the script ensures that critical entitlements defined in `container-runtime-linux.entitlements` and `container-network-vmnet.entitlements` remain intact, preserving the sandboxed virtualization capabilities required for network and runtime isolation.

**Idempotency**: The script checks whether the desired version is already installed and exits cleanly unless the `-f` force flag is provided, preventing unnecessary reinstallation cycles.

## Summary

- Stop the container daemon with `container system stop` before any upgrade operation.
- Run [`/usr/local/bin/update-container.sh`](https://github.com/apple/container/blob/main//usr/local/bin/update-container.sh) to automatically upgrade to the latest GitHub release.
- Use `-v <tag>` to install a specific version and `-f` to force reinstallation.
- Downgrade by running `/usr/local/bin/uninstall-container.sh -k` followed by the update script with the target version.
- The script preserves macOS entitlements and automatically handles architecture selection for Apple Silicon.

## Frequently Asked Questions

### How do I check my current Apple Container version before upgrading?

Run `container --version` in your terminal. This command outputs the version of the CLI tool and the underlying `container-apiserver`, allowing you to verify whether you need to upgrade or confirm that an upgrade succeeded.

### Can I upgrade Apple Container without stopping the service?

No. The update script explicitly requires you to run `container system stop` first. Attempting to upgrade while the daemon is active will cause the script to exit with an error, as running processes would interfere with the replacement of shared libraries and runtime binaries.

### What happens if the GitHub release only has an unsigned package?

The [`update-container.sh`](https://github.com/apple/container/blob/main/update-container.sh) script queries the GitHub API and prioritizes signed `.pkg` assets. If only an unsigned package is available, the script pauses and prompts you to confirm whether to proceed with the unsigned installation, ensuring you are aware of the security implications before continuing.

### Is it safe to downgrade Apple Container to a previous release?

Yes, provided you preserve your user data. Use `/usr/local/bin/uninstall-container.sh -k` to remove the current version while keeping your data, then run `/usr/local/bin/update-container.sh -v <older-tag>` to install the previous release. This process maintains your existing containers and configurations across the version change.