# How to Create a Named Volume in Apple Container > Learn how to create a named volume in Apple Container using the container volume create command. This guide explains the process and its internal mechanisms. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-05 --- **Apple Container creates named volumes through the `container volume create` command, which validates the name against a regex, generates an EXT4 image, and persists metadata via the `VolumesService` actor.** The apple/container repository provides a dedicated CLI sub-command for volume management that handles the entire lifecycle from creation to deletion. This guide explains the command syntax, validation rules, and underlying implementation details found in the service source code. ## The container volume create Command Apple Container exposes volume operations through the `container volume create` sub-command, with syntax documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md). The CLI sends an XPC request—identified as `volumeCreate` in `Sources/Services/ContainerAPIService/Client/XPC+.swift`—to the `VolumesService` actor, which orchestrates directory creation, filesystem initialization, and metadata persistence. ### Basic Syntax To create a named volume with default settings: ```bash container volume create mydata ``` The command accepts the volume name as the final positional argument. 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), the service validates the name using `VolumeStorage.isValidVolumeName` before proceeding. ### Validation Rules Volume names must match a regular expression enforced by the storage layer that permits only alphanumerics, hyphens (`-`), and underscores (`_`). If the name violates these rules, the service throws `VolumeError.invalidVolumeName`. ### Driver Options Customize the volume capacity and journaling behavior using the `--opt` flag: 1. **Size**: Allocate specific capacity with `--opt size=` ```bash container volume create --opt size=10g mydata ``` 2. **Journaling**: Configure the EXT4 journal mode and size with `--opt journal=[:]` ```bash container volume create --opt journal=writeback:64m mydata ``` ## Under the Hood: VolumesService Implementation The actual volume creation logic lives in the `VolumesService` actor. When the CLI invokes the command, the service executes a strict sequence of operations: - **Validation**: Checks the name against the regex and verifies the volume does not already exist. If a volume with the same name exists, the service returns `VolumeError.volumeAlreadyExists`. - **Directory Creation**: Provisions a directory under the resource root for the new volume. - **Image Generation**: Builds an EXT4 filesystem image stored as `volume.img`. - **Metadata Persistence**: Writes a JSON [`entity.json`](https://github.com/apple/container/blob/main/entity.json) description via `FilesystemEntityStore` ([`Sources/ContainerPersistence/FilesystemEntityStore.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/FilesystemEntityStore.swift)) to record volume configuration and driver options. ## Working with Named Volumes Once created, reference the volume in container runtime operations and maintenance commands. ### Mounting in Containers Attach the named volume to a container filesystem using the `-v` flag: ```bash container run -v mydata:/var/lib/app docker.io/python:3-alpine ``` This mounts the volume at `/var/lib/app` inside the container. ### Inspect and List View detailed metadata including size, labels, and mount point: ```bash container volume inspect mydata ``` Enumerate all available volumes: ```bash container volume list ``` ### Deletion Remove a volume permanently. This operation fails if the volume is currently attached to any container: ```bash container volume delete mydata ``` ## Summary - Invoke `container volume create ` to provision a named volume in Apple Container. - Names must satisfy the regex in `VolumeStorage.isValidVolumeName` to avoid `VolumeError.invalidVolumeName`. - Customize capacity and journaling via `--opt size=` and `--opt journal=[:]`. - The `VolumesService` actor handles creation by generating an EXT4 image and persisting [`entity.json`](https://github.com/apple/container/blob/main/entity.json) metadata. - Mount volumes in containers using the `-v` syntax; deletion requires the volume to be unattached. ## Frequently Asked Questions ### What characters are allowed in Apple Container volume names? Volume names must match the regular expression enforced by `VolumeStorage.isValidVolumeName`, which restricts input to alphanumerics, hyphens, and underscores. The service throws `VolumeError.invalidVolumeName` if validation fails. ### How do I set a specific size when creating a volume? Pass the `--opt size=` flag to `container volume create`. For example, `--opt size=10g` allocates 10 GiB. The `VolumesService` parses this option during the EXT4 image creation phase in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift). ### What happens if I try to create a volume that already exists? The `VolumesService` actor checks for existing entries before creation. If the name is already in use, it returns `VolumeError.volumeAlreadyExists` and the CLI reports the conflict without modifying the existing data. ### Where does Apple Container store volume metadata on disk? The system persists volume descriptions in a JSON [`entity.json`](https://github.com/apple/container/blob/main/entity.json) file within the volume's directory structure, handled by [`Sources/ContainerPersistence/FilesystemEntityStore.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/FilesystemEntityStore.swift). The actual filesystem data resides in a `volume.img` file created under the resource root.