Quick Verdict
Borgmatic isn't an alternative to BorgBackup — it's a wrapper around it. BorgBackup is the backup engine. Borgmatic is the automation layer that makes BorgBackup easier to configure, schedule, and monitor. Use BorgBackup directly for simple manual backups. Use Borgmatic for anything automated.
Overview
| Aspect | BorgBackup | Borgmatic |
|---|---|---|
| What it is | Backup engine (deduplication, encryption, compression) | Configuration wrapper + scheduler for BorgBackup |
| Requires | Nothing (standalone) | BorgBackup (dependency) |
| Configuration | Command-line flags per invocation | YAML config file (declarative) |
| Scheduling | Manual (cron/systemd timers) | Built-in schedule support + cron integration |
| Language | Python + C (performance-critical parts) | Python |
| License | BSD-3 | GPL-3 |
| Docker image | Community images | Official ghcr.io/borgmatic-collective/borgmatic
|
The relationship: BorgBackup does the actual work — reading files, deduplicating, compressing, encrypting, and writing to the repository. Borgmatic wraps those BorgBackup commands behind a YAML config file and adds features BorgBackup doesn't have: scheduling, hooks, health checks, database dumps, and monitoring integrations.
Feature Comparison
| Feature | BorgBackup (bare) | BorgBackup + Borgmatic |
|---|---|---|
| Create backups |
borg create command |
borgmatic (one command) |
| Configuration | Flags per command |
config.yaml (declarative) |
| Multiple repositories | Manual per-repo commands | Single config, multiple repos |
| Retention policies |
borg prune with flags |
Declarative in YAML |
| Consistency checks |
borg check manually |
Automatic per schedule |
| Pre-backup hooks | Shell scripts around borg | Built-in before_backup hooks |
| Post-backup hooks | Shell scripts around borg | Built-in after_backup hooks |
| Database dumps | Manual pg_dump/mysqldump | Built-in PostgreSQL/MySQL/MariaDB/SQLite dumps |
| Health monitoring | Manual | Healthchecks.io, Cronitor, PagerDuty, ntfy integrations |
| Error notifications | Manual | Built-in hooks for email, webhooks |
| Multiple source dirs | One borg create per set |
Single command, multiple source paths |
| Exclude patterns |
--exclude flags |
Clean YAML exclude lists |
| Docker deployment | Community images | Official Docker image with cron built-in |
When You Need Borgmatic
Use BorgBackup directly if:
- You run manual, one-off backups
- You have a simple single-directory backup to one repository
- You're comfortable writing shell scripts for automation
- You want minimal dependencies
Example direct BorgBackup workflow:
# Initialize
borg init --encryption=repokey ssh://backup@nas/~/borg-repo
# Backup
borg create ssh://backup@nas/~/borg-repo::backup-$(date +%Y%m%d) /data
# Prune old backups
borg prune --keep-daily=7 --keep-weekly=4 --keep-monthly=6 ssh://backup@nas/~/borg-repo
Use Borgmatic if:
- You want automated, scheduled backups
- You back up multiple directories or to multiple repositories
- You need pre/post backup hooks (database dumps, service stops)
- You want health monitoring integration
- You run in Docker and want a clean cron setup
Equivalent Borgmatic config:
# config.yaml
repositories:
- path: ssh://backup@nas/~/borg-repo
label: nas
source_directories:
- /data
- /config
exclude_patterns:
- '*.tmp'
- '.cache'
retention:
keep_daily: 7
keep_weekly: 4
keep_monthly: 6
consistency:
checks:
- repository
- archives
hooks:
before_backup:
- echo "Starting backup..."
after_backup:
- echo "Backup complete."
healthchecks:
ping_url: https://hc-ping.com/your-uuid
Run with a single command:
borgmatic
Docker Setup Comparison
BorgBackup in Docker (manual)
services:
borgbackup:
image: monachus/borgbackup:1.4.0
container_name: borgbackup
restart: unless-stopped
volumes:
- /data:/source:ro
- /backup:/repository
- ./borg-scripts:/scripts:ro
entrypoint: /scripts/backup.sh
You need to write your own backup.sh script handling init, create, prune, and check.
Borgmatic in Docker (automated)
services:
borgmatic:
image: ghcr.io/borgmatic-collective/borgmatic:2.1.3
container_name: borgmatic
restart: unless-stopped
volumes:
- /data:/source:ro
- /backup:/repository
- ./config.yaml:/etc/borgmatic/config.yaml:ro
- borgmatic-state:/root/.borgmatic
- borgmatic-cache:/root/.cache/borg
environment:
BORG_PASSPHRASE: "your-encryption-passphrase" # CHANGE THIS
TZ: UTC
CRON: "0 3 * * *" # Run daily at 3 AM
volumes:
borgmatic-state:
borgmatic-cache:
Borgmatic's Docker image includes cron built-in. Set the CRON environment variable and it handles scheduling automatically.
Database Backup Integration
One of Borgmatic's strongest features is built-in database dumping:
# config.yaml
postgresql_databases:
- name: nextcloud
hostname: postgres
port: 5432
username: nextcloud
password: changeme
mysql_databases:
- name: wordpress
hostname: mariadb
username: root
password: changeme
Borgmatic dumps the databases before creating the backup archive, ensuring consistent database snapshots. With bare BorgBackup, you'd write separate dump scripts and coordinate them with backup timing yourself.
The Verdict
| Scenario | Recommendation |
|---|---|
| Learning BorgBackup | Start with bare BorgBackup to understand the fundamentals |
| Production automated backups | Use Borgmatic — it's the community standard |
| Docker deployment | Borgmatic (official image with cron) |
| Multiple repos/sources | Borgmatic (single config handles everything) |
| Database backups | Borgmatic (built-in dump integration) |
| Monitoring/alerting | Borgmatic (Healthchecks.io integration) |
| One-off manual backups | BorgBackup directly |
Bottom line: If you're setting up automated BorgBackup, there's no reason not to use Borgmatic. It makes BorgBackup better without adding complexity. Think of it like Docker Compose for Docker — you can use Docker directly, but Compose makes everything more manageable.
FAQ
Do I need to install BorgBackup separately if I use Borgmatic?
If you use the Borgmatic Docker image (ghcr.io/borgmatic-collective/borgmatic), no — it bundles both BorgBackup and Borgmatic. If you install Borgmatic via pip on a host system, you need BorgBackup installed separately (apt install borgbackup or pip install borgbackup). Borgmatic does not include BorgBackup — it wraps it.
Can Borgmatic use existing BorgBackup repositories?
Yes. If you have an existing Borg repository created with borg init, point Borgmatic at it by setting the repository path in config.yaml. Borgmatic uses the same repository format — no migration needed. Your existing archives, retention history, and encryption keys all carry over.
Does Borgmatic support remote repositories over SSH?
Yes — it uses BorgBackup's SSH support. Set the repository path as ssh://user@hostname/path/to/repo in your Borgmatic config. The remote server needs BorgBackup installed. SSH key authentication is recommended (mount your SSH key into the Docker container if using the Borgmatic image).
Can I run Borgmatic without cron?
Yes. You can run borgmatic manually at any time. The Docker image includes cron built-in (set via the CRON or BACKUP_CRON environment variable), but you can also trigger backups on demand: docker compose exec borgmatic borgmatic. For integration with external schedulers (systemd timers, Kubernetes CronJobs), disable the built-in cron and trigger externally.
How do I test restores with Borgmatic?
Use borgmatic extract --archive latest --destination /tmp/restore-test to restore a specific archive to a test directory. Or use borgmatic mount --archive latest --mount-point /mnt/borg to FUSE-mount an archive and browse it. Regular restore testing is essential — a backup that cannot be restored is not a backup.
Can Borgmatic notify me if a backup fails?
Yes. Borgmatic supports multiple notification methods: on_error hooks (run shell commands on failure), Healthchecks.io pings (failed ping = alert), Cronitor, PagerDuty, ntfy, and custom webhook URLs. The Healthchecks.io integration is the most popular — create a check, add the ping URL to your config, and get alerted if a backup misses its schedule.
Top comments (0)