Settings

Configure django-snapshots by setting SNAPSHOTS in your Django settings module. Both a plain dict and a typed SnapshotSettings instance are accepted; either form is normalised to SnapshotSettings during AppConfig.ready().

# settings.py — dict style
SNAPSHOTS = {
    "STORAGE": {
        "BACKEND": "django_snapshots.storage.LocalFileSystemBackend",
        "OPTIONS": {"location": "/var/backups/snapshots"},
    },
    "SNAPSHOT_FORMAT": "directory",
    "DEFAULT_ARTIFACTS": ["database", "media", "environment"],
    "PRUNE": {"keep": 30, "keep_daily": 14, "keep_weekly": 8},
    "METADATA": {"env": "production"},
}

# settings.py — typed style (better IDE support)
from django_snapshots import SnapshotSettings, PruneConfig
from django_snapshots.storage import LocalFileSystemBackend

SNAPSHOTS = SnapshotSettings(
    storage=LocalFileSystemBackend(location="/var/backups/snapshots"),
    snapshot_format="directory",
    prune=PruneConfig(keep=30, keep_daily=14, keep_weekly=8),
    metadata={"env": "production"},
)

SnapshotSettings

class django_snapshots.SnapshotSettings(*args, **kwargs)

Bases: ConfigBase

Top-level django-snapshots configuration.

Set as the SNAPSHOTS Django setting. Accepts either a plain dict or a SnapshotSettings instance; both are normalised to SnapshotSettings in AppConfig.ready().

__init__(storage: ~typing.Any = None, snapshot_format: ~django_snapshots.defines.SnapshotFormat = SnapshotFormat.DIRECTORY, snapshot_name: str | ~typing.Callable[[~datetime.datetime], str] = '{timestamp_utc}', metadata: dict[str, ~typing.Any] = <factory>, encryption: ~typing.Any = None, database_connectors: dict[str, ~typing.Any] = <factory>, prune: ~django_snapshots.settings.PruneConfig | None = None) → None

database_connectors: dict[str, Any]

Per-alias database connector overrides.

encryption: Any = None

Encryption backend instance. None (default) disables encryption.

classmethod from_dict(data: dict[str, Any]) → SnapshotSettings

metadata: dict[str, Any]

Custom key/value metadata attached to every snapshot manifest.

prune: PruneConfig | None = None

Default retention policy used by snapshots prune when no flags are given.

snapshot_format: SnapshotFormat = 'directory'

Snapshot container format: "directory" (default) or "archive".

snapshot_name: str | Callable[[datetime], str] = '{timestamp_utc}'

Template string or callable for generating snapshot names.

storage: Any = None

Storage backend instance. Defaults to LocalFileSystemBackend rooted at the current working directory when not explicitly configured.

to_dict() → dict[str, Any]

PruneConfig

class django_snapshots.PruneConfig(keep: int | None = None, duration: relativedelta | None = None, max_size: int | None = None)

Bases: ConfigBase

Retention policy for the prune command.

Policies use union semantics: a snapshot is kept if any policy retains it.

__init__(keep: int | None = None, duration: relativedelta | None = None, max_size: int | None = None) → None

duration: relativedelta | None = None

Keep all snapshots newer than this duration (e.g. relativedelta(days=30)).

classmethod from_dict(data: dict[str, Any]) → PruneConfig

keep: int | None = None

Keep the N most recent snapshots.

max_size: int | None = None

Maximum total bytes to retain. At least one snapshot is always kept.

to_dict() → dict[str, Any]