How to back up a InfluxDB Docker container (2026)
The correct way to back up a InfluxDB container is a logical dump, not a file copy. Run `influx backup /backup/influx # (v2; v1 uses influxd backup -portable /backup)` inside the container and back up its output. Copying /var/lib/influxdb2 while influx is writing produces an inconsistent snapshot; the backup command snapshots TSM shards and metadata through the engine, so background compaction never leaves you with a torn on-disk copy.
What Dockstash detects
| Env keys detected | DOCKER_INFLUXDB_INIT_USERNAME, DOCKER_INFLUXDB_INIT_PASSWORD, DOCKER_INFLUXDB_INIT_ORG, INFLUXDB_HTTP_AUTH_ENABLED |
|---|---|
| Default port | 8086 |
| Live data paths (never copied live) | /var/lib/influxdb2, /var/lib/influxdb |
| Example images | influxdb:2.7, influxdb:2, influxdb:1.8, influxdb |
The dump command
influx backup /backup/influx # (v2; v1 uses influxd backup -portable /backup)The restore command
influx restore /backup/influx # (v1 uses influxd restore -portable /backup)the backup command snapshots TSM shards and metadata through the engine, so background compaction never leaves you with a torn on-disk copy.
Gotchas to avoid
- Never restic the live TSM/WAL directory — shards are compacted in the background so a raw copy is inconsistent.
- InfluxDB v2 uses `influx backup` (HTTP API + token); v1 uses `influxd backup -portable`. Dockstash detects the major version.
- v2 backups need an operator token with read access; without it the backup call is unauthorized.
Do it in one click with Dockstash
Dockstash runs the exact dump above, restics it off-site, and drill-tests the restore automatically — no script to maintain.
Last updated: July 2026
Frequently asked questions
What command backs up InfluxDB correctly?
For v2, `influx backup` against the HTTP API with an operator token. For v1, `influxd backup -portable`. Both snapshot TSM shards and metadata consistently. Dockstash detects the version and runs the right one.
Can I copy the shard files directly?
No. InfluxDB compacts TSM shards in the background, so a live directory copy is inconsistent. Use the backup command, which coordinates a consistent snapshot through the engine.
What token does the v2 backup need?
An operator (all-access) token with read permission on the buckets. Dockstash detects the init token env keys; supply a token if auth is enabled.
How do I restore a time series backup?
Use `influx restore` (v2) or `influxd restore -portable` (v1) against a fresh instance. Dockstash restores to a staging instance first before any overwrite.