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

You can upgrade Apple Container by stopping the daemon with container system stop and running /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 explicitly refuses to run while the container daemon is active to prevent data corruption or runtime conflicts.

Execute the following to halt the service:

container system stop

Upgrading to the Latest Version

The recommended upgrade path uses the 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:

container system stop

Step 2: Run the Update Script

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

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

The script performs the following actions as implemented in 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:

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:

/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:

/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:

/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 script (source available at 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 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 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.

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