# Volume Management Options for Apple Containers: Creating, Mounting, and Managing Persistent Storage

> Explore Apple container volume management options. Learn to create, mount, and manage persistent storage using the container CLI and API for named and anonymous volumes.

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

---

**Apple Containers provide comprehensive volume management capabilities through the `container` CLI and Container API, supporting named and anonymous volumes with options for creation, inspection, mounting, and pruning.**

The `apple/container` repository implements a robust storage subsystem that handles persistent data for containers through Swift-based services. Understanding the volume management options for Apple containers enables developers to efficiently provision storage, enforce naming conventions, and reclaim unused space. The implementation spans client-side parsing logic, server-side XPC services, and validation utilities written in Swift.

## Creating Named and Anonymous Volumes

Volumes in Apple containers can be provisioned explicitly as named volumes or generated automatically as anonymous volumes when mounting without a source.

### Named Volume Creation

Create explicit named volumes using the `container volume create` command with optional labels, driver-specific options, and size constraints:

```bash
container volume create [--label <label> …] [--opt <opt> …] [-s <size>] <name>

```

The command accepts three key parameters:

- `--label <label>` – Attach metadata key-value pairs to the volume.
- `--opt <opt>` – Specify driver-specific options such as `journal=ordered`.
- `-s <size>` – Set initial size with byte suffixes (K, M, G, T, P).

The creation logic resides in [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift) (lines 317-395), which handles validation and storage allocation. Driver options are parsed in [`VolumesHarness.swift`](https://github.com/apple/container/blob/main/VolumesHarness.swift) (lines 45-48), defaulting to the `"local"` driver if omitted.

### Anonymous Volume Generation

When running containers with mount points that lack explicit source paths, the system auto-generates anonymous volumes. The `VolumeStorage.generateAnonymousVolumeName()` function in [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift) (lines 52-56) creates UUID-based names prefixed with `anon-`.

```bash
container run -v /data image:latest  # Creates anon-<uuid> automatically

```

## Mounting Volumes at Container Runtime

Bind volumes into running containers using the `-v` or `--volume` flag, or the more verbose `--mount` syntax. The CLI parser in [`Sources/Services/ContainerAPIService/Client/Parser.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Parser.swift) (lines 447-523) handles both formats through `Parser.volumes` and `Parser.mount`.

```bash

# Mount named volume

container run -v mydata:/var/lib/app image:latest

# Mount with read-only restriction

container run -v mydata:/var/lib/app:ro image:latest

# Host path bind (creates anonymous volume)

container run -v /host/path:/data image:latest

```

## Listing, Inspecting, and Deleting Volumes

The volume lifecycle management commands provide complete visibility and control over persistent storage assets.

### Core Management Commands

- **`container volume list [-q|--quiet]`** – Display all volumes; use `-q` to return only names.
- **`container volume inspect <name>`** – Output JSON details for specific volumes, including mount points, labels, and usage statistics.
- **`container volume delete <name> …`** – Remove specific volumes; blocked if referenced by running containers.
- **`container volume prune`** – Delete all volumes with no container references and report reclaimed space.

These operations are implemented in [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift) (lines 30-250) and exposed via the XPC bridge in [`VolumesHarness.swift`](https://github.com/apple/container/blob/main/VolumesHarness.swift).

## Disk Usage Reporting and Storage Metrics

Monitor storage consumption using the system disk-free command. The `container system df` utility reports total, active, and reclaimable space for volumes through `VolumesService.calculateDiskUsage()` in [`Sources/Services/ContainerAPIService/Server/DiskUsage/DiskUsageService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/DiskUsage/DiskUsageService.swift) (lines 46-68).

```bash
container system df

```

## Volume Naming Rules and Validation

Apple containers enforce strict naming conventions through `VolumeStorage.isValidVolumeName` in [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift) (lines 38-45).

**Validation requirements:**

- Pattern: `^[A-Za-z0-9][A-Za-z0-9_.-]*$`
- Maximum length: 255 characters
- Must start with alphanumeric character

**Default configuration:**

- Default size: 512 GB (`VolumeStorage.defaultVolumeSizeBytes` in lines 38-40)
- Anonymous naming: Lowercase UUID strings

## Driver Support and Configuration Options

The current implementation supports only the **`local`** driver. Attempting to specify unsupported drivers triggers `VolumeError.driverNotSupported` (lines 28-33 in [`VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/VolumeConfiguration.swift)).

Configure volume behavior using `--opt` key-value pairs passed during creation:

```bash
container volume create --opt journal=ordered --opt size=10g mydata

```

## Complete Volume Management Example

The following workflow demonstrates the full volume lifecycle:

```bash

# Create a 10GiB volume with specific journaling options

container volume create \
    --opt journal=ordered \
    --opt size=10g \
    mydata

# Run container with volume mounted read-only

container run \
    -v mydata:/var/lib/app:ro \
    ghcr.io/example/app:latest

# Inspect volume configuration

container volume inspect mydata

# Clean up unused volumes

container volume prune

```

## Summary

- **Apple containers** provide comprehensive volume management through the `container` CLI and underlying Swift services in the `apple/container` repository.
- **Named volumes** are created explicitly via `container volume create` with support for labels, size constraints, and driver options, while **anonymous volumes** generate UUID-based names automatically.
- **Validation rules** enforce alphanumeric naming with 255-character limits, and **storage defaults** begin at 512 GB unless overridden.
- **Lifecycle management** includes listing, inspecting, deleting, and pruning operations implemented in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) and [`VolumesHarness.swift`](https://github.com/apple/container/blob/main/VolumesHarness.swift).
- **Disk usage** is tracked through `calculateDiskUsage()` in [`DiskUsageService.swift`](https://github.com/apple/container/blob/main/DiskUsageService.swift), accessible via `container system df`.
- Only the **local driver** is currently supported, with configuration passed through `--opt` parameters.

## Frequently Asked Questions

### How do I create a volume with a specific size in Apple containers?

Use the `-s` flag with size suffixes. For example, `container volume create -s 10g myvolume` creates a 10-gigabyte volume. The size parser accepts K, M, G, T, and P suffixes. The default size is 512 GB as defined in `VolumeStorage.defaultVolumeSizeBytes` in [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift).

### What happens when I delete a volume that is currently in use?

The `container volume delete` command blocks removal if the volume is referenced by any running or stopped containers. You must stop and remove dependent containers before deleting the volume. This safety check is implemented in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) to prevent data loss.

### Can I use custom storage drivers with Apple containers?

No. Currently, only the `local` driver is supported. The `VolumesHarness` defaults to `"local"` if no driver is specified, and attempting to use an unsupported driver raises `VolumeError.driverNotSupported` as defined in [`VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/VolumeConfiguration.swift). Custom driver support may be added in future releases.

### How do I identify which volumes are consuming the most disk space?

Run `container system df` to see total, active, and reclaimable space across all volumes. For detailed JSON output of specific volumes, use `container volume inspect <name>`, which includes size and usage metadata calculated by [`DiskUsageService.swift`](https://github.com/apple/container/blob/main/DiskUsageService.swift).