vaultwarden-to-keepass

Export your Vaultwarden/Bitwarden vault into multiple backup formats: KeePass database, JSON, and ZIP (with attachments).

Fork information

This repository is a fork of davidnemec/bitwarden-to-keepass. All props to davidnemec for the original work.

Changes in this fork

• JSON export of the full personal vault and all organizations
• ZIP export with attachments (bw export --format zip)
• KeePass export now includes all item types: Logins, Secure Notes, SSH Keys, Cards, Identities
• TOTP support for otpauth://, steam://, and plain secret formats
• Password history stored as protected custom properties
• SSH Keys stored with private key (protected), public key, and fingerprint
• Cards stored with number and CVV as protected properties
• Parallel attachment downloads using ThreadPoolExecutor
• Progress logging per item ([1/280] Processing "...")
• Configurable Dockerfile with build args for Python image and CLI version
• CLI version pinned to 2025.11.0 for Vaultwarden 1.35.x compatibility
• Bitwarden CLI installed as native binary (not npm) for better performance

How does it work?

It uses the official bitwarden-cli to export items from your Vaultwarden/Bitwarden vault. The container runs fully automatically — login, unlock, sync, export, lock, logout — no interaction needed.

Export formats

Format	Contents	Use case
KeePass (.kdbx)	All item types, TOTP, SSH keys, cards, identities, attachments, password history, custom fields	Offline access with KeePassXC/KeePassDX
JSON	Vault data without attachments	Quick readable backup, Bitwarden reimport
ZIP	Vault data with attachments	Full Bitwarden-native backup for reimport

Environment variables

Variable	Required	Default	Description
DATABASE_PASSWORD	yes	—	Password for the KeePass file
BW_CLIENTID	yes	—	API key Client ID (user.xxxxx)
BW_CLIENTSECRET	yes	—	API key Client Secret
BW_MASTER_PW	yes	—	Vaultwarden master password
DATABASE_NAME	no	bitwarden.kdbx	KeePass filename
BITWARDEN_URL	no	—	Custom Vaultwarden URL (leave empty for official Bitwarden)
EXPORT_PATH	no	/exports/json	Directory for JSON and ZIP exports
SKIP_KEEPASS	no	false	Set to true to skip KeePass export
SKIP_JSON	no	false	Set to true to skip JSON export
SKIP_ZIP	no	false	Set to true to skip ZIP export
WORKERS	no	4	Number of parallel workers for attachment downloads

Usage

Docker command

docker run --rm \
     -e DATABASE_PASSWORD=keepass-password \
     -e DATABASE_NAME=vaultwarden.kdbx \
     -e BITWARDEN_URL=https://vault.example.com \
     -e BW_CLIENTID=user.your-client-id \
     -e BW_CLIENTSECRET=your-client-secret \
     -e BW_MASTER_PW=your-master-password \
     -e EXPORT_PATH=/exports/json \
     -v /path/to/exports:/exports \
     registry.example.com/vaultwarden_to_keepass:latest

Example output

Connecting to Bitwarden instance at https://vault.example.com
You are logged in!
Syncing complete.
Generating exports...
  KeePass: /exports/vaultwarden.kdbx (skip: false)
  JSON:    /exports/json (skip: false)
  ZIP:     /exports/json (skip: false)
2026-04-06 20:59:29 :: INFO :: Exporting personal vault as JSON...
2026-04-06 20:59:31 :: INFO :: Personal vault exported to: /exports/json/bw_vault_export_20260406_205929.json
2026-04-06 20:59:31 :: INFO :: Fetching organizations...
2026-04-06 20:59:33 :: INFO :: No organizations found, skipping organization export.
2026-04-06 20:59:33 :: INFO :: Exporting personal vault as ZIP (with attachments)...
2026-04-06 20:59:37 :: INFO :: Personal vault ZIP exported to: /exports/json/bw_vault_export_20260406_205933.zip (203531 bytes)
2026-04-06 20:59:37 :: INFO :: KeePass database does not exist, creating a new one.
2026-04-06 20:59:40 :: INFO :: Folders done (72).
2026-04-06 20:59:42 :: INFO :: Starting to process 280 items.
2026-04-06 20:59:42 :: INFO :: No attachments to download.
2026-04-06 20:59:42 :: INFO :: Building KeePass entries...
2026-04-06 20:59:42 :: INFO :: [1/280] Processing "@home"
...
2026-04-06 20:59:42 :: INFO :: [280/280] Processing "zoraxy"
2026-04-06 20:59:42 :: INFO :: Saving changes to KeePass database.
2026-04-06 20:59:42 :: INFO :: KeePass export completed.
Your vault is locked.
You have logged out.
Export completed successfully

Output files

exports/
├── vaultwarden.kdbx                              # KeePass database
└── json/
    ├── bw_vault_export_20260406_205929.json       # JSON export
    └── bw_vault_export_20260406_205933.zip        # ZIP export (with attachments)

Building

Standard build

docker build -t vaultwarden-backup .

Build arguments

Argument	Default	Description
PYTHON_IMAGE	python:3-slim-trixie	Base Python Docker image
BW_CLI_VERSION	2025.11.0	Bitwarden CLI version (pinned for Vaultwarden compatibility)

# Default (Python 3 + Trixie + CLI 2025.11.0)
docker build -t vaultwarden-backup .
 
# Specific CLI version
docker build --build-arg BW_CLI_VERSION=2025.11.0 -t vaultwarden-backup .
 
# Different base image
docker build --build-arg PYTHON_IMAGE=python:3-slim-bookworm -t vaultwarden-backup .
 
# Tag and push to registry
docker build -t registry.example.com/vaultwarden_to_keepass:latest .
docker push registry.example.com/vaultwarden_to_keepass:latest

Known issues

Bitwarden CLI compatibility with Vaultwarden

CLI versions 2025.12.0 and newer have compatibility issues with Vaultwarden 1.35.x, causing toWrappedAccountCryptographicState or userDecryptionOptions errors on login. The CLI is therefore pinned to 2025.11.0.

Relevant issues:

• vaultwarden #6709 — CLI login fix
• vaultwarden #6729 — CLI 2025.12.0 compatibility
• bitwarden/clients #19413 — toWrappedAccountCryptographicState crash
• vaultwarden #6966 — Discussion

Passkeys / FIDO2

Passkeys cannot be exported — this is by design as the private keys never leave the authenticator.

Backup script example

For automated backups with WebDAV upload and file rotation, see backup_vaultwarden_to_keepass.sh. It supports:

• Upload of KeePass, JSON, and ZIP to WebDAV (e.g. Nextcloud/OpenCloud)
• File rotation: keeps last 7 daily, last 4 weekly, last 12 monthly exports
• Crontab compatible

Credits

• Original project: davidnemec/bitwarden-to-keepass
• Bitwarden CLI
• pykeepass