Skip to main content

vbart

GitHub PyPI PyPI - Status GitHub last commit GitHub issues PyPI - Downloads GitHub repo size PyPI - Python Version


vbart logo

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.

Metadata

Release files for vbart 0.4.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vbart 0.4.6
File Size Uploaded Provenance Actions
vbart-0.4.6.tar.gz 19.5 kB With provenance Details for vbart-0.4.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vbart 0.4.6
File Interpreter ABI Platform Actions
vbart-0.4.6-py3-none-any.whl Python 3 none any Details for vbart-0.4.6-py3-none-any.whl

Total release size: 42.9 kB

Release files / vbart-0.4.6.tar.gz

Download URL vbart-0.4.6.tar.gz
Size 19.5 kB
Tags Source
SHA-256 checksum
How to use checksums
31bbfd73956cac316ad266c68a23624e3e925945734513f077329e8b91eb71b3
BLAKE2b-256 checksum
How to use checksums
a3893c8e5384a24fff5caef73caecbf16f11af7c92b0d3f805f7f33a8a5fce5c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / vbart-0.4.6-py3-none-any.whl

Download URL vbart-0.4.6-py3-none-any.whl
Size 23.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b226ccdbc0fa40757bfb451ad351b8befcdf8d2e5143f31efff8a89b2482e73
BLAKE2b-256 checksum
How to use checksums
185b4e6a090ff0ccf5ae31f544ddbc5083036c99680cd8b1e20be31db6a71a93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for vbart 0.4.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vbart-0.4.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page