# Named vs Anonymous Volumes in Container CLI: Creation, Lifecycle, and Management

> Understand the difference between named vs anonymous volumes in containers. Learn about creation, lifecycle, and management for efficient data persistence.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: deep-dive
- Published: 2026-06-12

---

**Named volumes use explicit identifiers you define and persist until manually removed, while anonymous volumes auto-generate UUID-based names when you omit the source path, yet both share the same storage layer and persist beyond container lifecycles.**

The `apple/container` repository provides a lightweight container runtime where volume management is handled through two distinct patterns: explicitly named volumes and auto-generated anonymous volumes. Understanding the difference between these volume types is essential for data persistence strategies, as each behaves differently during creation and identification while sharing identical underlying storage mechanisms.

## What Are Named Volumes?

A **named volume** is a storage entity created with a user-supplied identifier that follows the pattern `^[A-Za-z0-9][A-Za-z0-9_.-]*$`. These volumes provide persistent storage that survives container restarts and removals, making them ideal for databases or shared data layers.

### Creation and Naming

You create named volumes explicitly using the `container volume create` command or implicitly by referencing a name in a mount specification. When you use `-v mydata:/app/data` or `--mount type=volume,src=mydata,dst=/app/data`, the CLI validates the name against the regex pattern defined in [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift).

Named volumes remain visible in `container volume list` under their assigned identifiers. Because you control the naming scheme, you can easily reference them across multiple container runs and orchestrate complex workflows where containers share state.

## What Are Anonymous Volumes?

An **anonymous volume** is a storage volume automatically generated by the runtime when you mount a path without specifying a source name. Instead of failing or erroring, the CLI creates a volume with a UUID-based name in the format `anon-{36-char-uuid}`.

### Automatic Generation

When parsing mount strings in [`Sources/Services/ContainerAPIService/Client/Parser.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Parser.swift), the CLI detects when you omit the source component (e.g., `container run -v /data alpine` or `--mount type=volume,dst=/data`). In this case, the parser invokes `VolumeStorage.generateAnonymousVolumeName()` to produce a unique identifier.

These volumes appear in `container volume list` prefixed with `anon-`, making them distinguishable from user-created volumes. Despite the auto-generated name, anonymous volumes persist in the store until explicitly removed and are **not** automatically cleaned up when containers exit, even when using the `--rm` flag.

## Key Differences Between Named and Anonymous Volumes

| Feature | Named Volume | Anonymous Volume |
|---------|--------------|------------------|
| **Creation** | Explicit via `container volume create` or implicit with `-v <name>:<path>` | Implicit when `-v <path>` is used without source |
| **Naming** | User-defined string matching `^[A-Za-z0-9][A-Za-z0-9_.-]*$` | Auto-generated UUID (`anon-{36-char-uuid}`) |
| **Visibility** | Listed under custom name | Listed with `anon-` prefix |
| **Lifecycle** | Persists until `container volume rm` or `prune` | Persists until `container volume rm` or `prune` (not tied to `--rm`) |
| **Typical Use** | Shared data between containers, databases | Temporary scratch space, single-container cache |

## How Volume Creation Works Under the Hood

### Parsing Mount Strings

The [`Parser.swift`](https://github.com/apple/container/blob/main/Parser.swift) file handles the `-v` and `--mount` flags. When a mount specification lacks a source component, the parser marks the mount as a volume type and triggers anonymous generation. For named volumes, the parser validates the supplied name against `VolumeStorage.isValidVolumeName`.

### Name Validation and Storage

Both volume types undergo identical validation defined in [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift). The storage layer, implemented in [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift), uses `FilesystemEntityStore<VolumeConfiguration>` to persist metadata. Whether the name is user-defined or UUID-generated, the storage mechanism treats it uniformly as a lookup key.

### UUID Generation

The `generateAnonymousVolumeName()` function produces a 36-character UUID prefixed with `anon-`. This ensures uniqueness while maintaining compatibility with the standard volume name validation rules, as UUIDs satisfy the alphanumeric requirements.

## Practical Usage Examples

```bash

# Create a named volume for persistent database storage

container volume create mydata

# Run a container with the named volume attached

container run -v mydata:/app/data alpine ls /app/data

# Remove the named volume when no longer needed

container volume rm mydata

```

```bash

# Create an anonymous volume for temporary build cache

container run -v /tmp/cache alpine sh -c "echo hello > /tmp/cache/msg"

# List volumes to find the anonymous one (note the anon- prefix)

container volume list

# Re-use the anonymous volume by referencing its full ID

VOL=$(container volume list -q | grep anon)
container run -v $VOL:/tmp/cache alpine cat /tmp/cache/msg

# Clean up anonymous volumes

container volume rm $VOL

# Or remove all unused volumes

container volume prune

```

## Cleanup and Maintenance

Neither named nor anonymous volumes are garbage collected automatically when containers stop. The `container volume prune` command removes any volume—regardless of type—that is not currently referenced by a running container. According to the documentation in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), developers must explicitly manage volume lifecycle using `rm` or `prune` commands to reclaim disk space.

## Summary

- **Named volumes** require explicit creation with user-defined identifiers following the pattern `^[A-Za-z0-9][A-Za-z0-9_.-]*$`, stored via `VolumesService` using `FilesystemEntityStore<VolumeConfiguration>`.
- **Anonymous volumes** auto-generate UUID-based names via `generateAnonymousVolumeName()` in [`VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/VolumeConfiguration.swift) when mount strings omit the source path.
- Both volume types persist independently of container lifecycles and require manual cleanup via `container volume rm` or `container volume prune`.
- The [`Parser.swift`](https://github.com/apple/container/blob/main/Parser.swift) client logic distinguishes between volume types during CLI argument parsing, while the storage layer treats both identically.

## Frequently Asked Questions

### Do anonymous volumes get deleted automatically when a container exits with `--rm`?

No. Anonymous volumes persist in the volume store even when containers are run with the `--rm` flag. You must manually remove them using `container volume rm` or `container volume prune` to reclaim space, as documented in the command reference.

### Can I convert an anonymous volume to a named volume?

There is no direct conversion command. To effectively convert an anonymous volume, you would need to create a new named volume and copy the data from the anonymous volume, or use the anonymous volume's UUID (prefixed with `anon-`) as a reference in subsequent commands, though this is not recommended for long-term management.

### Do both volume types use the same storage driver and validation?

Yes. Both named and anonymous volumes use the same `FilesystemEntityStore<VolumeConfiguration>` backend in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) and must satisfy `VolumeStorage.isValidVolumeName`. Anonymous volumes always pass validation because the UUID generation produces strings matching the required alphanumeric pattern.

### How do I identify which volumes are anonymous in the volume list?

Anonymous volumes appear in `container volume list` with the `anon-` prefix followed by a 36-character UUID. Named volumes appear under their user-defined names without this prefix, making it easy to distinguish between manually managed storage and auto-generated volumes.