# How to Utilize Anonymous Volumes and Manage Their Lifecycle in apple/container

> Learn how to use anonymous volumes in apple/container for automatic persistent storage. Discover how to manage their lifecycle and delete them efficiently.

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

---

**Anonymous volumes in apple/container automatically provision persistent storage with UUID-based names when you omit the source path in a mount specification, persist after container exit, and require manual deletion via `container volume delete` or `container volume prune` when no longer referenced.**

Anonymous volumes provide a lightweight storage mechanism in the apple/container ecosystem that eliminates the need for manual naming while maintaining full lifecycle control. When you run a container with a mount that specifies only a destination path, the CLI generates a unique identifier and persists data to the VolumeStorage directory exactly like a named volume. Understanding how these volumes are created in `VolumesService._create`, tracked via the `VolumeConfiguration` model, and safely destroyed is essential for effective storage management.

## Creating Anonymous Volumes

Anonymous volumes are generated automatically whenever you provide a mount specification without a source name. According to the source code in [`Sources/Services/ContainerAPIService/Client/Parser.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Parser.swift) (lines 35-46), the parser sets `ParsedVolume.isAnonymous = true` when the source field is empty.

You can create an anonymous volume using either Docker-style syntax or the mount flag:

```bash

# Docker-style syntax creates an anonymous volume mounted at /data

container run -v /data alpine:latest

# Alternative using --mount syntax without source

container run --mount type=volume,dst=/data alpine:latest

```

When executing these commands, `VolumesService._create` generates a UUID-based name following the pattern `anon-{36-char-uuid}` and stores the volume in the runtime's VolumeStorage directory. The `VolumeConfiguration` model marks the volume with `isAnonymous = true` (see [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift), lines 55-62).

## Lifecycle and Persistence Characteristics

### Automatic Generation and Naming

Unlike named volumes that require explicit identification, anonymous volumes receive automatically generated identifiers. The system creates a directory named `anon-<uuid>` and records this in the volume configuration, making the volume discoverable through standard CLI commands without requiring you to memorize custom names.

### Persistence Beyond Container Exit

Anonymous volumes persist on disk exactly like named volumes. They remain available after the container exits and are not automatically garbage collected. This behavior ensures data survival across container restarts and allows you to re-attach the storage to new container instances by referencing the generated ID.

### Visibility and Inspection

You can identify anonymous volumes using the list command with JSON output, which reveals the `isAnonymous` flag added during `VolumeResource` serialization (lines 56-57 of VolumesService.swift):

```bash
container volume inspect anon-1e2f3d4c-5b6a-7d8e-9f0a-b1c2d3e4f5g6

```

The output includes `"isAnonymous": true`, distinguishing these volumes from explicitly named ones.

## Managing Anonymous Volume Lifecycle

### Listing and Identifying Anonymous Volumes

To view all anonymous volumes and extract their IDs for scripting:

```bash

# Show only volume IDs (quiet mode) and filter for anonymous

container volume list -q | grep anon

```

This returns the UUID-based names that you can use in subsequent commands.

### Re-attaching to New Containers

Since anonymous volumes are functionally identical to named volumes after creation, you can mount them in new containers by specifying the generated ID:

```bash

# Capture the most recent anonymous volume ID

VOL=$(container volume list -q | grep anon | tail -n1)

# Re-attach to a new container

container run -v $VOL:/data alpine:latest

```

The same storage is now accessible inside the new container at the specified mount point.

### Manual Deletion and Safety Guards

Anonymous volumes are **not** removed when running containers with `--rm`. You must explicitly delete them. The system implements safety checks in `VolumesService._delete` (lines 76-86) that atomically verify no containers reference the volume before allowing deletion:

```bash

# Delete a specific anonymous volume

container volume delete anon-1e2f3d4c-5b6a-7d8e-9f0a-b1c2d3e4f5g6

```

If the volume remains attached to any container (running or stopped), the command fails with a "volume in use" error. This prevents accidental data loss.

For bulk cleanup, use the prune command to remove all unused volumes:

```bash

# Remove all volumes not attached to any container

container volume prune

```

This command safely identifies volumes with zero container references and reclaims disk space.

## Practical Code Examples

### Creating and Verifying an Anonymous Volume

```bash

# Start a container with an anonymous volume

container run -v /app/data --name test alpine:latest touch /app/data/file.txt

# List volumes to see the generated ID

container volume list

```

### Inspecting Volume Metadata

```bash

# Get detailed JSON including the isAnonymous flag

container volume inspect $(container volume list -q | grep anon | head -n1)

```

Sample output excerpt:

```json
{
  "name": "anon-1e2f3d4c-5b6a-7d8e-9f0a-b1c2d3e4f5g6",
  "driver": "local",
  "isAnonymous": true,
  "mountpoint": "/var/lib/container/volumes/anon-1e2f3d4c-5b6a-7d8e-9f0a-b1c2d3e4f5g6"
}

```

### Complete Lifecycle Workflow

```bash

# 1. Create container with anonymous volume

CID=$(container run -d -v /data alpine:latest sh -c "echo 'persistent data' > /data/file.txt")

# 2. Extract the volume ID from the container JSON

VOL=$(container inspect $CID | grep -o 'anon-[a-f0-9-]\{36\}')

# 3. Remove container (volume persists)

container rm $CID

# 4. Use volume in new container

container run -v $VOL:/data alpine:latest cat /data/file.txt

# 5. Clean up when done

container volume delete $VOL

```

## Summary

- **Anonymous volumes** generate UUID-based names (`anon-*`) automatically when you specify a mount destination without a source in `container run` commands.
- They **persist after container exit** and are tracked in `VolumeConfiguration` with `isAnonymous = true`, visible in `container volume list` and inspect output.
- The `VolumesService._delete` function enforces safety by blocking deletion of volumes still attached to any container (running or stopped).
- **Manual cleanup is required** using `container volume delete <id>` or `container volume prune`, as the `--rm` flag does not remove anonymous volumes.

## Frequently Asked Questions

### How do anonymous volumes differ from named volumes in apple/container?

Anonymous volumes function identically to named volumes in terms of storage mechanics and persistence. The only difference is the naming convention—anonymous volumes receive auto-generated UUIDs (`anon-<uuid>`) while named volumes use user-specified identifiers. Both are stored in the same VolumeStorage directory and tracked through the `VolumeConfiguration` model, but anonymous volumes set `isAnonymous = true` during creation in `VolumesService._create`.

### Why isn't my anonymous volume deleted when I use `container run --rm`?

The `--rm` flag only removes the container layer, not associated volumes. According to the implementation in [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift), anonymous volumes are designed to persist beyond the container lifecycle to prevent accidental data loss. You must explicitly delete them using `container volume delete` or clean up unused volumes with `container volume prune` after confirming no containers reference them.

### How can I identify which anonymous volumes are safe to delete?

Run `container volume list` to see all volumes, then use `container volume inspect <id>` to check the `"isAnonymous"` field. To verify safety for deletion, attempt to remove the volume—the atomic check in `_delete` (lines 76-86) will reject the operation if any container (running or stopped) still references the volume, ensuring you cannot delete actively used storage.

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

While there is no direct "rename" command in the CLI, you can achieve equivalent functionality by creating a new named volume and copying data from the anonymous volume, or by referencing the anonymous volume's ID in subsequent container runs as you would with a named volume. The UUID-based name functions as a stable identifier for re-attachment regardless of the volume type.