To restore a Docker Compose named volume on macOS, stop the services that write to it, identify the exact Docker volume name, and extract the backup archive into that volume with a temporary container. Docker Desktop keeps Linux volumes inside its Linux VM, so use the Docker CLI to access them rather than trying to edit Docker’s internal files in Finder. Docker’s volume guide explains the container-based restore method, and Docker Desktop’s networking overview describes the Linux VM used on Mac.

Before you restore: check the archive and Compose project

Make sure Docker Desktop is running, then open Terminal and change to the directory containing your Compose file. Find the archive in Finder, or confirm its name in Terminal. The examples below assume it is named backup.tar in a folder named backup-files; adjust those values to match your files.

Inspect the archive’s contents before extracting it. This helps you establish whether the files are stored directly at the archive root or under a parent directory such as data/.

tar -tf "$HOME/backup-files/backup.tar" | head -30

The head command limits the listing to the first 30 paths; it does not change the archive. Note whether the paths start with a directory prefix. You will need to extract the right level into the application’s data directory. Docker’s documented example uses --strip 1 because its archive contains a top-level directory; do not use that option automatically if your archive has no such prefix. Docker’s restore example shows how the extraction path affects the restored layout.

Identify the exact volume name

A Compose volume key such as db-data may not be the Docker volume’s full name. Compose commonly prefixes it with the project name, but a volume configured with name: or external: true can use another name. The Compose volumes reference explains those naming options.

List volumes and inspect the Compose configuration to determine which one your service uses:

docker volume ls
docker compose config

In the rendered Compose configuration, find the service’s volume mapping and the resolved volume name. If you need to inspect a candidate, run docker volume inspect VOLUME_NAME, replacing VOLUME_NAME with the actual name. Confirm it belongs to the intended project and service before proceeding; restoring into the wrong volume can overwrite unrelated data.

Stop writers and restore the backup

Stop the Compose services before restoring so the application does not change files during extraction. Running docker compose down stops and removes the project’s containers and networks; by default it keeps named volumes. Avoid adding -v or --volumes, which removes Compose-managed named volumes. Docker’s compose down reference lists this behavior.

docker compose down

Set a shell variable to the exact volume name you confirmed, then extract the archive using a temporary container. This example uses the official alpine image, mounts the backup folder read-only, and mounts the target volume at /restore. Replace myproject_db-data if your actual name differs. The image must be available locally or Docker must be able to pull it.

VOLUME_NAME='myproject_db-data'
BACKUP_DIR="$HOME/backup-files"

docker run --rm \
  --mount "type=volume,source=$VOLUME_NAME,target=/restore" \
  --mount "type=bind,source=$BACKUP_DIR,target=/backup,readonly" \
  alpine sh -c 'cd /restore && tar -xf /backup/backup.tar --strip-components=1'

This command assumes the archive has one enclosing directory level, for example data/file.db. If the archive listing showed files directly at its root, remove --strip-components=1. If the paths have a different common prefix, choose the number of components to remove so the application’s expected files land directly under /restore. The --mount syntax explicitly attaches a named volume and a host directory; Docker documents these mount options and the restore pattern in its volume guide.

The extraction replaces files with matching paths but does not clear unrelated files already in the volume. If you need an exact mirror of the backup, a merge-style extraction is insufficient: first make a separate backup of the current volume, then use a deliberate cleanup procedure after confirming the archive and target. Do not run a broad delete command against a volume you have not identified.

Start the project and check the result

Start the Compose services again:

docker compose up -d

Compose reuses an existing volume declared in the project, while creating one if it is missing. The Compose volumes reference documents that behavior. Check the service logs and, where applicable, use the application’s own integrity or database recovery checks. Confirm the expected records or files are present before treating the restore as complete.

If the service reports an empty data directory, recheck the volume name, the host directory path, and the archive’s directory structure. Also verify that the archive is compatible with the application version and that its backup was taken in a state the application can recover from. A successful tar extraction only confirms files were unpacked; it does not establish that application data is valid.

Sources