Pyzotero
Pyzotero is a Python wrapper for the Zotero API v3. Use it to programmatically manage Zotero libraries: read items and collections, create and update references, upload attachments, manage tags, and export citations.
Authentication Setup
Required credentials — get from https://www.zotero.org/settings/keys:
-
User ID: shown as "Your userID for use in API calls"
-
API Key: create at https://www.zotero.org/settings/keys/new
-
Library ID: for group libraries, the integer after /groups/ in the group URL
Store credentials in environment variables or a .env file:
ZOTERO_LIBRARY_ID=your_user_id ZOTERO_API_KEY=your_api_key ZOTERO_LIBRARY_TYPE=user # or "group"
See references/authentication.md for full setup details.
Installation
uv add pyzotero
or with CLI support:
uv add "pyzotero[cli]"
Quick Start
from pyzotero import Zotero
zot = Zotero(library_id='123456', library_type='user', api_key='ABC1234XYZ')
Retrieve top-level items (returns 100 by default)
items = zot.top(limit=10) for item in items: print(item['data']['title'], item['data']['itemType'])
Search by keyword
results = zot.items(q='machine learning', limit=20)
Retrieve all items (use everything() for complete results)
all_items = zot.everything(zot.items())
Core Concepts
-
A Zotero instance is bound to a single library (user or group). All methods operate on that library.
-
Item data lives in item['data'] . Access fields like item['data']['title'] , item['data']['creators'] .
-
Pyzotero returns 100 items by default (API default is 25). Use zot.everything(zot.items()) to get all items.
-
Write methods return True on success or raise a ZoteroError .
Reference Files
File Contents
references/authentication.md Credentials, library types, local mode
references/read-api.md Retrieving items, collections, tags, groups
references/search-params.md Filtering, sorting, search parameters
references/write-api.md Creating, updating, deleting items
references/collections.md Collection CRUD operations
references/tags.md Tag retrieval and management
references/files-attachments.md File retrieval and attachment uploads
references/exports.md BibTeX, CSL-JSON, bibliography export
references/pagination.md follow(), everything(), generators
references/full-text.md Full-text content indexing and retrieval
references/saved-searches.md Saved search management
references/cli.md Command-line interface usage
references/error-handling.md Errors and exception handling
Common Patterns
Fetch and modify an item
item = zot.item('ITEMKEY') item['data']['title'] = 'New Title' zot.update_item(item)
Create an item from a template
template = zot.item_template('journalArticle') template['title'] = 'My Paper' template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'} zot.create_items([template])
Export as BibTeX
zot.add_parameters(format='bibtex') bibtex = zot.top(limit=50)
bibtex is a bibtexparser BibDatabase object
print(bibtex.entries)
Local mode (read-only, no API key needed)
zot = Zotero(library_id='123456', library_type='user', local=True) items = zot.items()