or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

archives.mdindex.mdmaintenance.mdmount.mdrepository.mdutilities.md
tile.json

tessl/pypi-borgbackup

Deduplicated, encrypted, authenticated and compressed backups

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/borgbackup@1.4.x

To install, run

npx @tessl/cli install tessl/pypi-borgbackup@1.4.0

index.mddocs/

BorgBackup

BorgBackup is a deduplicating backup program that provides efficient and secure data backup through content-defined chunking deduplication, authenticated encryption (AES-256 with HMAC-SHA256), and multiple compression algorithms. It supports both local and remote backups over SSH with mountable backup archives as filesystems for easy restore operations.

Package Information

  • Package Name: borgbackup
  • Package Type: pypi
  • Language: Python (with C/Cython extensions)
  • Installation: pip install borgbackup

Core Imports

For JSON API programming:

import subprocess
import json

For internal API access (not recommended, unstable):

import borg
from borg.archiver import main
from borg.repository import Repository
from borg.archive import Archive

Basic Usage

Command-Line Interface with JSON Output (Recommended)

import subprocess
import json

# List archives with JSON output
result = subprocess.run(['borg', 'list', '--json', '/path/to/repo'], 
                       capture_output=True, text=True, check=True)
archives = json.loads(result.stdout)

# Get archive info
result = subprocess.run(['borg', 'info', '--json', '/path/to/repo::archive-name'], 
                       capture_output=True, text=True, check=True)
archive_info = json.loads(result.stdout)

# Create archive with JSON stats (--json implies --stats)
result = subprocess.run(['borg', 'create', '--json', 
                        '/path/to/repo::archive-{now}', '/home/user/documents'], 
                       capture_output=True, text=True, check=True)
create_stats = json.loads(result.stdout)

# List archive contents with JSON Lines output
result = subprocess.run(['borg', 'list', '--json-lines', '/path/to/repo::archive-name'], 
                       capture_output=True, text=True, check=True)
files = [json.loads(line) for line in result.stdout.strip().split('\n') if line]

Note: JSON support is selective in BorgBackup. Commands with --json support: create, info, list (repositories), recreate, import-tar. Commands with --json-lines support: diff, list (archive contents).

Repository Initialization

# Initialize encrypted repository
borg init --encryption=repokey /path/to/repo

# Initialize with passphrase encryption
borg init --encryption=keyfile /path/to/repo

Architecture

BorgBackup's architecture consists of several key components:

  • Repository: Storage backend managing segments, manifest, and metadata
  • Archives: Individual backup snapshots with deduplication across time
  • Chunks: Content-defined variable-size data blocks for deduplication
  • Cache: Local metadata cache for performance optimization
  • Encryption: AES-256 encryption with HMAC-SHA256 authentication

The tool uses content-defined chunking for cross-file and cross-archive deduplication, making it highly space-efficient for incremental backups.

Capabilities

Repository Operations

Repository initialization, configuration, and maintenance operations including creation, checking, and upgrades.

# Repository initialization
subprocess.run(['borg', 'init', '--encryption=repokey', repository_path])

# Repository info
result = subprocess.run(['borg', 'info', '--json', repository_path], 
                       capture_output=True, text=True, check=True)

# Repository check
subprocess.run(['borg', 'check', repository_path])

Repository Management

Archive Operations

Archive creation, extraction, listing, and deletion operations for managing backup snapshots.

# Create archive
subprocess.run(['borg', 'create', '--json',
               f'{repository_path}::{archive_name}', *source_paths])

# List archives
result = subprocess.run(['borg', 'list', '--json', repository_path],
                       capture_output=True, text=True, check=True)

# Extract archive
subprocess.run(['borg', 'extract', f'{repository_path}::{archive_name}'])

Archive Operations

Pruning and Maintenance

Archive pruning, repository maintenance, and cleanup operations for managing backup retention policies.

# Prune archives by retention policy
subprocess.run(['borg', 'prune', '--keep-daily=7', '--keep-weekly=4', 
               '--keep-monthly=6', repository_path])

# Compact repository
subprocess.run(['borg', 'compact', repository_path])

Pruning and Maintenance

Mount and Access

Mounting archives as filesystems for browsing and selective file restoration.

# Mount archive as filesystem
subprocess.run(['borg', 'mount', f'{repository_path}::{archive_name}', mount_point])

# Unmount
subprocess.run(['borgfs', 'umount', mount_point])

Mount and Access

Utility Operations

Version information, help system, benchmarking, and advanced lock management for BorgBackup operations.

# Get version information
result = subprocess.run(['borg', 'version'], capture_output=True, text=True, check=True)

# Benchmark performance
subprocess.run(['borg', 'benchmark', 'crud', repository_path, '/tmp/benchmark'])

# Run command with repository lock
subprocess.run(['borg', 'with-lock', repository_path, 'custom-command'])

Utility Operations

Types

class RepositoryInfo:
    """Repository information structure"""
    def __init__(self):
        self.cache: dict
        self.security_dir: str
        self.repository: dict  # Contains id, last_modified, location
        self.encryption: dict  # Contains mode, keyfile
        
class ArchiveInfo:
    """Archive information structure"""
    def __init__(self):
        self.name: str
        self.id: str
        self.start: str  # ISO timestamp
        self.end: str    # ISO timestamp
        self.duration: float
        self.stats: dict  # Contains original_size, compressed_size, deduplicated_size
        
class CreateResult:
    """Result of archive creation"""
    def __init__(self):
        self.archive: dict      # Archive metadata
        self.repository: dict   # Repository state
        self.cache: dict       # Cache statistics

Error Handling

BorgBackup uses exit codes for error signaling:

  • 0: Success
  • 1: Warning (operation succeeded, but there were warnings)
  • 2: Error (operation failed)
  • 128+N: Killed by signal N

Common exceptions when using subprocess:

  • subprocess.CalledProcessError: Command execution failed
  • json.JSONDecodeError: Invalid JSON response
  • FileNotFoundError: Borg executable not found