Migrate from Bitwarden Cloud to Vaultwarden on a VPS

Why migrate to self-hosted Vaultwarden

What Vaultwarden offers over Bitwarden cloud

• Fixed monthly cost: the price of your VPS, not a per-user or per-feature subscription.
• Organization vaults and collections at no extra cost: available from installation, not reserved to a premium plan.
• Built-in TOTP: two-factor authentication codes stored in Vaultwarden, no Bitwarden Premium plan required.
• Data on your infrastructure: no third party has access to your encrypted vault or connection logs.
• Full compatibility with official Bitwarden clients: no change in habits for your users.
• Very low resource usage: less than 50 MB of RAM at rest, runs on the smallest VPS alongside other services.

Prerequisites before starting

SMTP_HOST=smtp.example.com
[email protected]
SMTP_PORT=587
SMTP_SECURITY=starttls
[email protected]
SMTP_PASSWORD=yourpassword

Migrating from Bitwarden cloud to Vaultwarden: complete procedure

1. 01

   Authenticate to Bitwarden cloud with the CLI

   Open a terminal and log in to your Bitwarden cloud account. The CLI authenticates to the official server by default — do not change the server target yet; this command must target Bitwarden cloud, not your Vaultwarden:

   bw login

   Enter your email and master password. If you have TOTP or a security key enabled, the CLI will prompt you. Once authenticated, unlock the vault and export the session key:

   export BW_SESSION=$(bw unlock --raw)

   The --raw flag is essential: without it, bw unlock displays a multi-line formatted message instead of the raw key, and subsequent commands using $BW_SESSION will return an authentication error. This is one of the most common errors in this process.

   Verify the session is valid:

   bw status

   The response should show "status": "unlocked".

2. 02

   Export your personal vault in Bitwarden JSON format

   Exporting in the native Bitwarden JSON format (bitwardenjson) preserves all metadata: entry types, custom fields, URIs, notes, TOTP. Do not use CSV format, which loses this information.

   bw export --format bitwardenjson --output ./bitwarden-personal.json

   Attention : This file does not contain your attachments. This is the most significant gap in the standard export. Attachments must be downloaded separately, entry by entry (step 4). Note that credit card credentials, identities, and secure notes are included in this export.

   The JSON file is client-side encrypted — it contains your data in cleartext (protected only by file permissions). Store it in a private directory and delete it after import.

3. 03

   Export each organization separately

   Organization data is not included in the personal vault export. Each organization must be exported with its own identifier.

   First list your organizations to retrieve their identifiers:

   bw list organizations

   For each organization displayed, note its id and export it:

   bw export --organizationid <organization-id> --format bitwardenjson --output ./bitwarden-org-<name>.json

   Repeat this command for each organization. If you have three organizations, you will get three separate JSON files.

   If the command returns a permission error, verify that you are the owner or administrator of the organization in the Bitwarden web interface. A member without export rights cannot use this command.

4. 04

   Download attachments

   This is the step most guides skip. The JSON export lists entries but does not contain attached files — neither their content nor even their name.

   For each entry that has an attachment, use the bw get attachment command:

   bw list items | jq '.[] | select(.attachments != null) | {id, name, attachments}'

   This command lists entries with attachments. For each attachment, download it by specifying the item identifier and the file name:

   bw get attachment <file-name> --itemid <entry-id> --output ./attachments/

   Replace <file-name> with the exact attachment name as it appears in the JSON list, and <entry-id> with the corresponding Bitwarden entry id.

   If you have many attachments, this bash script automates the download:

   mkdir -p ./attachments
   bw list items | jq -c '.[] | select(.attachments != null)' | while read item; do
     ITEM_ID=$(echo $item | jq -r '.id')
     ITEM_NAME=$(echo $item | jq -r '.name')
     echo $item | jq -c '.attachments[]' | while read att; do
       ATT_ID=$(echo $att | jq -r '.id')
       ATT_NAME=$(echo $att | jq -r '.fileName')
       bw get attachment "$ATT_NAME" --itemid "$ITEM_ID" --output "./attachments/${ITEM_ID}_${ATT_NAME}"
     done
   done

   Note: jq must be installed on your machine (apt install jq or brew install jq).

5. 05

   Import into Vaultwarden

   First redirect the CLI to your Vaultwarden instance. This is the irreversible operation in this procedure: the CLI can only point to one server at a time.

   bw config server https://vault.yourdomain.com

   Authenticate to Vaultwarden:

   bw logout
   bw login
   export BW_SESSION=$(bw unlock --raw)

   Import the personal vault:

   bw import bitwardenjson ./bitwarden-personal.json

   For organizations, you must first create the organization in the Vaultwarden web interface, then retrieve its identifier:

   bw list organizations

   Then import each organization file with the newly created identifier:

   bw import bitwardenjson ./bitwarden-org-<name>.json --organizationid <new-id>

   Finally, manually re-attach downloaded attachments to their entries through the Vaultwarden web interface: navigate to the entry, click "Edit", then add the attachment from the ./attachments/ directory.

6. 06

   Verify the import and update clients

   Before considering the migration complete, perform these checks:

   In the Vaultwarden web interface, verify:
   - the number of entries matches that of Bitwarden cloud;
   - custom fields are present on a few reference entries;
   - TOTP codes work (test a code);
   - organizations and their collections are visible.

   On Bitwarden clients (browser extension, mobile app):
   - log out of the Bitwarden cloud account;
   - in the client settings, change the server URL to https://vault.yourdomain.com;
   - log back in with the same credentials.

   Wait for full sync before deleting anything on the old cloud account. Keep access to Bitwarden cloud active for at least 48 hours after migration to verify if in doubt.

Post-migration configuration

0 3 * * * tar -czf /backup/vaultwarden-$(date +%Y%m%d).tar.gz /opt/vaultwarden/data/ 2>/dev/null

Troubleshooting: common errors

export BW_SESSION=$(bw unlock --raw)

Your self-hosted vault is operational