Registry / database / pykeepass

pykeepass

JSON →
library4.1.1.post1pypypi✓ verified 87d ago

PyKeePass is a Python library that enables interaction with KeePass databases, supporting both KDBX3 and KDBX4 formats. It allows users to read, create, update, and save entries and groups within a KeePass file. The library is actively maintained with frequent releases, typically every few months.

pip install pykeepass
INSTALL
IMPORT
SIG · PYKEEPASS
P
pykeepass
databasepythonv4.1.1.post1
Install
3.1s avg
Import
428ms
Disk
41MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.1.1.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.450s · 41.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.1s · import 0.406s · 42MB
41MB installed
● package 41MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PyKeePass
from pykeepass import PyKeePass

This quickstart demonstrates how to create a new KeePass database, open an existing one, add a new entry, find an entry by its title, retrieve its credentials, update its properties, and save the changes. Ensure you set the `KEEPASS_MASTER_PASSWORD` environment variable or replace the placeholder password.

import os from pykeepass import PyKeePass, create_database DB_PATH = 'my_database.kdbx' MASTER_PASSWORD = os.environ.get('KEEPASS_MASTER_PASSWORD', 'supersecurepassword') # Create a new KeePass database if not os.path.exists(DB_PATH): print(f"Creating new database at {DB_PATH}") kp = create_database(filename=DB_PATH, password=MASTER_PASSWORD) # Add a root group if it doesn't exist (create_database usually handles this) # kp.add_group(kp.root_group, 'General') kp.save() # Open an existing KeePass database print(f"Opening database: {DB_PATH}") kp = PyKeePass(DB_PATH, password=MASTER_PASSWORD) # Add a new entry if it doesn't exist if not kp.find_entries(title='Example Entry', first=True): print("Adding new entry: 'Example Entry'") # The path argument should be a list of strings for group hierarchy (v4.0.0+) entry = kp.add_entry(kp.root_group, 'Example Entry', 'testuser', 'entry_password_123', notes='This is a test entry.') print(f"Added entry: {entry.title} ({entry.username})") else: print("Entry 'Example Entry' already exists.") # Find an entry and retrieve its password entry = kp.find_entries(title='Example Entry', first=True) # Use first=True for a single entry if entry: print(f"Found entry '{entry.title}'. Username: {entry.username}, Password: {entry.password}") # Update an entry entry.notes = 'Updated notes for the test entry.' entry.tags = ['web', 'test'] print(f"Entry notes updated: {entry.notes}") print(f"Entry tags updated: {entry.tags}") else: print("Entry 'Example Entry' not found.") # Save changes to the database kp.save() print("Database saved successfully.") # Clean up (optional) # os.remove(DB_PATH) # print(f"Cleaned up: Removed {DB_PATH}")
Debug
Known issues
breakingStarting with version 4.0.0, path arguments for methods like `find_groups`, `find_entries`, `add_group`, and `add_entry` changed from a single string (e.g., 'Group/Subgroup') to a list of strings representing the hierarchical components (e.g., ['Group', 'Subgroup']).
fix
Update string path arguments to be lists of path components. For example, `kp.find_groups(path='social')` becomes `kp.find_groups(path=['social'])`.
affects: >=4.0.0
gotchaMethods like `find_entries()` and `find_groups()` return a *list* of matching objects by default, even if only one item matches. Directly accessing attributes (e.g., `entry.password`) on the result without specifying `first=True` or indexing the list (`[0]`) will result in an `AttributeError`.
fix
When expecting a single result, use the `first=True` argument (e.g., `kp.find_entries(title='MyEntry', first=True)`) or explicitly access the first element of the returned list (e.g., `kp.find_entries(title='MyEntry')[0]`).
affects: All
behavioralAs of version 4.1.0, the `Entry.tags` property now returns an empty list `[]` when an entry has no tags defined, instead of `None`. Code that checks for `if entry.tags is None:` might need adjustment to `if not entry.tags:` or `if len(entry.tags) == 0:`.
fix
Review logic that checks the `Entry.tags` property for `None` and update it to correctly handle an empty list as an indication of no tags.
affects: >=4.1.0
Errors
Common errors & fixes
pykeepass.exceptions.CredentialsError: raised when password/keyfile or transformed key are wrong
The provided password or keyfile is incorrect, or the KeePass database file is corrupted, preventing pykeepass from decrypting it.
fix
Double-check the master password and ensure the path to any associated keyfile (if used) is correct. If credentials are certain, the database file might be corrupted, in which case a backup should be used or the database repaired.
FileNotFoundError: [Errno 2] No such file or directory
The path specified for the KeePass database file (.kdbx) or a keyfile (.key) is incorrect, or the file does not exist at that location.
fix
Verify that the file path is accurate, including the filename and extension, and that the file actually exists at the given path. Use an absolute path or ensure the relative path is correct from the script's execution directory.
TypeError: a bytes-like object is required, not 'str'
The pykeepass library functions, particularly those dealing with binary data like attachments or certain custom properties, expect byte strings but received a regular Python string.
fix
Convert the string to a byte string using the `.encode()` method (e.g., `my_string.encode('utf-8')`) before passing it to the pykeepass function.
AttributeError: 'list' object has no attribute 'password'
Methods like `kp.find_entries()` or `kp.find_groups()` return a list of matching objects by default, even if only one match is found. Users commonly attempt to access attributes directly on this list instead of an individual `Entry` or `Group` object.
fix
If you expect a single result, pass `first=True` to the search method (e.g., `entry = kp.find_entries(title='MyEntry', first=True)`). Otherwise, iterate through the list or access a specific element by index (e.g., `entry = entries_list[0]`).
Upgrade
Version history
4.1.1.post1latest on PyPI · released Mar 6, 2025
Audit
Dependencies
pycryptodomerequiredCryptography operations for KeePass database encryption/decryption.
lxmlrequiredXML parsing and manipulation of the KeePass database structure.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
pykeepass — pip install pykeepass · libregistry