Registry / communication / pyzotero

pyzotero

JSON →
library1.13.1pypypi✓ verified 87d ago

Python wrapper for the Zotero API, enabling programmatic access to Zotero libraries for managing research references, collections, and items. It's currently at version 1.11.0 and typically releases new versions every few months, often including bug fixes and minor enhancements.

pip install pyzotero
INSTALL
IMPORT
SIG · PYZOTERO
P
pyzotero
communicationpythonv1.13.1
Install
4.5s avg
Import
717ms
Disk
26MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.13.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.754s · 28.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 4.5s · import 0.680s · 29MB
26MB installed
● package 26MB
Code
Verified usage

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

Zotero
from pyzotero import Zotero
import pyzotero.Zotero
The Zotero class is directly importable from the top-level package.

This quickstart initializes the Zotero client and fetches the first few collections and items from your library. It demonstrates accessing nested data fields and uses environment variables for secure credential management.

import os from pyzotero import Zotero # Your Zotero user ID or group ID library_id = os.environ.get('ZOTERO_LIBRARY_ID', 'YOUR_LIBRARY_ID') # Replace 'YOUR_LIBRARY_ID' if not using env var # Your Zotero API key api_key = os.environ.get('ZOTERO_API_KEY', 'YOUR_API_KEY') # Replace 'YOUR_API_KEY' if not using env var # 'user' for personal library, 'group' for group library library_type = 'user' if not library_id or not api_key: print("Please set ZOTERO_LIBRARY_ID and ZOTERO_API_KEY environment variables or replace placeholders.") else: try: # Initialize Zotero object zot = Zotero(library_id, library_type, api_key) # Fetch top-level collections collections = zot.collections() print(f"Found {len(collections)} collections.") if collections: print(f"First collection name: {collections[0]['data']['name']}") # Fetch 5 items from the library items = zot.items(limit=5) print(f"Found {len(items)} items.") if items: print(f"First item title: {items[0]['data']['title']}") except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
gotchaZotero API responses for items and collections are nested under a 'data' key. Direct access like `item['title']` will raise a KeyError.
fix
Always access item or collection properties via `item['data']['title']` or `collection['data']['name']`.
affects: All versions
gotchaMethods like `zot.items()` and `zot.collections()` return paginated results, often limited to 25 or 50 items by default. They do not retrieve all results in a single call.
fix
To retrieve all items or collections, use the `all_items()` or `all_collections()` methods (e.g., `zot.all_items()`). Alternatively, implement manual pagination using `limit` and `start` parameters.
affects: All versions
gotchaZotero API keys are tied to specific permissions (e.g., read, write, modify). An API key lacking necessary permissions will result in authentication errors or disallowed operation errors.
fix
Before making API calls, verify that your Zotero API key has the required permissions configured in your Zotero account settings (https://www.zotero.org/settings/keys).
affects: All versions
Errors
Common errors & fixes
KeyError: 'title' (or similar for other fields like 'name')
Attempting to access item or collection data directly (e.g., `item['title']`) instead of through the nested `data` dictionary.
fix
Access fields via `item['data']['title']` or `collection['data']['name']`. The Zotero API response structure always wraps core data in a 'data' field.
pyzotero.lib.ZoteroException: Could not authenticate with Zotero API. (401: Unauthorized)
Incorrect `library_id`, `api_key`, or `library_type` ('user' vs 'group'). Also, insufficient API key permissions are a common cause.
fix
Double-check your `library_id`, `api_key`, and ensure the `library_type` matches your Zotero setup. Verify that the API key has the necessary permissions (e.g., read access for fetching data) in your Zotero account.
(No explicit error, but unexpected behavior) "I'm only getting 25 items, but my Zotero library has hundreds."
Using paginated methods like `zot.items()` which by default return a limited number of results (e.g., 25 or 50) per call, without explicitly handling further pages.
fix
For comprehensive lists, use `zot.all_items()` or `zot.all_collections()`. These methods handle pagination internally to retrieve all available entries. Alternatively, use the `limit` and `start` parameters on `zot.items()` for manual pagination.
Upgrade
Version history
1.13.1latest on PyPI · released Jun 8, 2026
Audit
Dependencies
requestsrequiredUsed for making HTTP requests to the Zotero API.
Agent activity
26 hits · last 30 days
node
24
OpenAI (training)
1
Resources
pyzotero — pip install pyzotero · libregistry