vbart

Volume Backup And Restoration Tool for Docker

Backing up named Docker volumes can be difficult. There is an extension for Docker Desktop, but vbart is a simple, easy-to-use command-line tool for backing up and restoring named Docker volumes.

With vbart, you can:

• Backup a single named volume.
• Backup all active named volumes on your host.
• Backup just the volumes you list in a separate file.
• Restore a single backup to a named volume.

Backups are stored as compressed tar archives. Once you create a backup, you can copy it off-host or restore it on another machine.

Installation

Install it with pipx:

pipx install vbart

Alternatively, you can create a separate virtual environment and install it the traditional way:

pip3 install vbart

You can also install it with uv:

uv tool install vbart

Development and releases

Install uv, just, and git-cliff, then run just setup and the complete local quality gate, just check. Pull-request titles must use Conventional Commits; just changelog previews entries that will appear in the next release.

Prepare a release with just bump 0.5.0 (or a PEP 440 prerelease such as 0.5.0rc1), merge the release preparation pull request, then run just tag-release from an up-to-date main. Release CI validates, builds, and smoke-tests the artifacts, publishes prereleases to TestPyPI and stable releases to PyPI through Trusted Publishing, and creates the GitHub Release.

Runtime Support

vbart supports:

• Linux hosts with Docker.
• Windows hosts with Docker Desktop when Docker is running Linux containers.

Windows container mode is not supported.

vbart honors Docker connection environment variables such as DOCKER_HOST, DOCKER_TLS_VERIFY, and DOCKER_CERT_PATH. It does not follow DOCKER_CONTEXT or the Docker CLI currentContext; set DOCKER_HOST explicitly when you need to target a non-default Docker daemon.

Usage

For an overview, run:

vbart -h

The package can also be run as a module:

python -m vbart -h

Backup a Single Volume

vbart backup [-c COMPRESSION] volume_name

For example, to back up a volume named mysql_db, use:

vbart backup mysql_db

vbart will then create a backup file in your current working directory named:

YYYYMMDD-mysql_db-backup.tar.gz

The default compression algorithm is gzip. Use --compression (or -c) to choose another supported algorithm:

vbart backup --compression zstd mysql_db

Supported values are gzip, xz, zstd, bzip2, bzip3, 7z, and zip.

Backup Multiple Volumes

vbart backups [-v VOLUMES] [-c COMPRESSION]

Note the plural command name (backups as opposed to backup). VOLUMES is the optional name of a text file that contains case- sensitive volume names, one per line, that you want to back up. Within VOLUMES, blank lines and lines beginning with # are ignored, so you can comment the file if you wish.

If VOLUMES is not specified, all active Docker volumes on the current host are backed up. All volume backups are saved in the current working directory and named:

YYYYMMDD-{volume_name}-backup.tar.gz

Use --compression (or -c) to choose the compression algorithm for all archives created by the command.

Restore a Single Volume

vbart restore backup_file volume_name

The first argument (backup_file) is the compressed tar archive you created when you made a backup. vbart detects the compression format from supported suffixes such as .tar.gz, .tar.xz, .tar.zst, .tar.bz2, .tar.bz3, .tar.7z, and .tar.zip.

The second argument (volume_name) is the named volume to create from the backup. If the named volume already exists, vbart will terminate with no action. Otherwise, a new empty volume will be created with the given name and the backup will be restored to that volume.

Refresh vbart

If vbart is interrupted during execution, for example by pressing Ctrl+C, there may be dangling Docker containers that still reference existing volumes. Running the refresh command will clear those dangling containers.

Also, when you run vbart for the first time, it creates a small Alpine-based Docker image to perform the actual backups. This image is called vbart_utility. The refresh command also deletes the utility image, causing it to be recreated the next time you run vbart.

To refresh vbart, use:

vbart refresh

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

This project uses the docker library which is licensed under the Apache 2.0 License. The full license text can be found in the LICENSE-APACHE-2_0 file.