# Borgmatic Vs Borgbackup

## 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:

```bash
# 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:

```yaml
# 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:

```bash
borgmatic
```

## Docker Setup Comparison

### BorgBackup in Docker (manual)

```yaml
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)

```yaml
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:

```yaml
# 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.

## Related

- [How to Self-Host BorgBackup](/apps/borgbackup)
- [How to Self-Host Borgmatic](/apps/borgmatic)
- [Restic vs BorgBackup](/compare/restic-vs-borgbackup)
- [Restic vs Kopia vs BorgBackup](/compare/restic-vs-kopia-vs-borgbackup)
- [Kopia vs Restic](/compare/kopia-vs-restic)
- [Best Self-Hosted Backup Solutions](/best/backup)
- [Self-Hosted Alternatives to CrashPlan](/replace/crashplan)
- [Backup Strategy](/foundations/backup-strategy)