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

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.

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, 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 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. The storage layer, implemented in 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

# 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

# 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, 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 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 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 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.

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