bitwarden-py

A Python wrapper for the Bitwarden CLI — programmatically manage your Bitwarden vault: create, read, edit and delete items, folders, collections, attachments, and more.

Requirements

Bitwarden CLI

bitwarden-py calls the official bw binary under the hood, so you must have it installed and available in your PATH.

Install it by following the official guide:
👉 https://bitwarden.com/help/cli/#download-and-install

Quick install options:

# macOS (Homebrew)
brew install bitwarden-cli

# Windows (Chocolatey)
choco install bitwarden-cli

# npm (cross-platform)
npm install -g @bitwarden/cli

After installation, verify it works:

bw --version

Installation

pip install bitwarden-py

Or with uv:

uv add bitwarden-py

Quick Start

from bitwarden_py import Bitwarden

bw = Bitwarden(
    email="your@email.com",
    password="your_master_password",
)

# Fetch a password by item name
db_password = bw.get_password("My Database")
print(db_password)  # → "s3cr3t!"

# Update the password of an item
bw.edit_password("My Database", "n3wp@ssw0rd")

Logging in with MFA

If your account has multi-factor authentication (MFA) enabled, import MFAMethod and pass both mfa_method and mfa_code when creating the client:

from bitwarden_py import Bitwarden, MFAMethod

bw = Bitwarden(
    email="your@email.com",
    password="your_master_password",
    mfa_method=MFAMethod.TOTP,
    mfa_code=input("Enter your current MFA code: ").strip(),
)

db_password = bw.get_password("My Database")

Choose the method enabled for your account:

Pass the code as a string to preserve any leading zeros. Both parameters must be provided and the code must be non-empty; the library only adds the CLI's --method and --code options when both values are supplied. You can combine these parameters with server_url for a different server.

MFA parameters are used only when a new login is required. If the CLI is already logged in to the same account and server, the client reuses that login. Call bw.logout() before creating another client if you need to log in again, and provide a fresh MFA code.

Using a self-hosted server

By default the library points to https://vault.bitwarden.eu.
Pass server_url to connect to a different instance:

bw = Bitwarden(
    email="your@email.com",
    password="your_master_password",
    server_url="https://bitwarden.yourcompany.com",
)

API Reference

For the full Bitwarden CLI documentation, see 👉 https://bitwarden.com/help/cli/

Bitwarden(email, password, server_url?, mfa_method?, mfa_code?)

Creates a new client, authenticates if needed, and syncs the vault. If the CLI is logged in to a different account or server, it logs out before authenticating with the requested account and server.

MFAMethod is available via from bitwarden_py import MFAMethod. Its members map to the CLI method IDs: TOTP = "0", Email = "1", and Yubikey = "2". See Logging in with MFA for an example.

Create

bw.create_item(item) → dict

Creates a new vault item. Use bw.get_template("item") to obtain the base structure.

template = bw.get_template("item")
template["name"] = "My Login"
template["login"]["username"] = "user@example.com"
template["login"]["password"] = "s3cr3t"
new_item = bw.create_item(template)

bw.create_folder(folder) → dict

Creates a new folder. Use bw.get_template("folder") to obtain the base structure.

template = bw.get_template("folder")
template["name"] = "Work"
new_folder = bw.create_folder(template)

bw.create_attachment(file_path, item_id) → dict

Attaches a file to an existing vault item.

bw.create_attachment("./secret.txt", "16b15b89-65b3-4639-ad2a-95052a6d8f66")

Read

bw.get_password(item_name) → str

Returns the password of the vault item matching item_name.

bw.get_item(id_or_name) → dict

Returns the full vault item object matching the given ID or name.

bw.get_username(id_or_name) → str

Returns the username of the vault item matching the given ID or name.

bw.get_notes(id_or_name) → str

Returns the notes of the vault item matching the given ID or name.

bw.get_uri(id_or_name) → str

Returns the URI of the vault item matching the given ID or name.

bw.get_totp(id_or_name) → str

Returns the current TOTP code for the vault item matching the given ID or name.

bw.get_template(object_type) → dict

Returns the JSON template for the given object type. Useful for constructing objects to pass to create_* and edit_* methods.

Supported types: item, item.field, item.login, item.login.uri, item.card, item.identity, item.securenote, folder, collection, item-collections, org-collection.

bw.list_items(search?, folder_id?, collection_id?, organization_id?, url?, trash?) → list[dict]

Returns a list of vault items. All parameters are optional and act as filters.

bw.list_folders(search?) → list[dict]

Returns a list of folders, optionally filtered by search.

bw.list_collections(organization_id?, search?) → list[dict]

Returns a list of collections, optionally filtered by organization ID or search term.

bw.list_organizations(search?) → list[dict]

Returns a list of organizations, optionally filtered by search.

Edit

bw.edit_password(item_name, new_password) → None

Updates the password of the vault item matching item_name.

bw.edit_item(item_id, item) → dict

Replaces a vault item with the provided dict. Fetch the current item with get_item first, modify it, then pass it here.

item = bw.get_item("7ac9cae8-5067-4faf-b6ab-acfd00e2c328")
item["login"]["password"] = "newp@ssw0rd"
bw.edit_item(item["id"], item)

bw.edit_folder(folder_id, folder) → dict

Replaces a folder with the provided dict.

Delete

bw.delete_item(item_id, permanent?) → None

Sends an item to the trash. Pass permanent=True to delete it immediately without going through trash.

bw.delete_folder(folder_id, permanent?) → None

Deletes a folder. Pass permanent=True to skip trash.

bw.delete_attachment(attachment_id, item_id) → None

Deletes an attachment from a vault item.

Generate

bw.generate_password(length?, lowercase?, uppercase?, number?, special?) → str

Generates a random password using the Bitwarden CLI.

password = bw.generate_password()
# → e.g. "aB3!xK9@mN2#pQ"

strong = bw.generate_password(length=24, special=True)
pin = bw.generate_password(length=6, lowercase=False, uppercase=False, special=False)

Session

bw.logout() → None

Logs out of the Bitwarden vault and clears the local session.

bw.sync() → None

Downloads the encrypted vault from the Bitwarden server. Useful when you have made changes in another Bitwarden client (web vault, browser extension, mobile app) and want the CLI to reflect the latest state.

License

MIT