zotero-bridge

Python SDK for the Zotero debug-bridge — programmatically manage your Zotero library via HTTP.

Install

pip install zotero-bridge

Or from source:

git clone https://github.com/Xp-speit2018/zotero-bridge.git
cd zotero-bridge
pip install -e ".[dev]"

Quick start

from zotero_bridge import ZoteroBridge

bridge = ZoteroBridge()

# Lookup existing items
lookup = bridge.lookup("10.1109/DAC63849.2025.11132862", "DOI", include_attachments=True)
usenix = bridge.lookup("https://www.usenix.org/conference/osdi25/presentation/lou", "url")

# Backward-compatible duplicate check
dup = bridge.check_duplicate("10.1109/DAC63849.2025.11132862", "DOI")

# Add by identifier (magic wand)
item = bridge.add_by_identifier("10.1109/DAC63849.2025.11132862", "DOI")

# Auto-fetch PDF
bridge.find_fulltext(item["itemID"])

# Add note + tag
bridge.add_note(item["itemID"], "Key insight: ...")
bridge.add_tag(item["itemID"], "to-read")

# Download PDF bytes
pdf = bridge.get_pdf_bytes(item["itemID"])

Configuration

Environment variables (optional):

Or a .env file (requires python-dotenv):

ZOTERO_BRIDGE_URL=http://localhost:23120
ZOTERO_BRIDGE_TOKEN=zotero-debug

CLI lookup

Look up existing Zotero items and print JSON:

zotero-lookup --doi "10.1109/DAC63849.2025.11132862" --attachments --notes
zotero-lookup --paper-url "https://www.usenix.org/conference/osdi25/presentation/lou" --attachments
zotero-lookup --title "Attention Is All You Need" --first

CLI ingestion workflow

A ready-made pipeline that checks for duplicates, fetches metadata + PDF, creates DBLP-style venue collections, and aliases items into a project collection:

# Auto-derive venue from metadata
zotero-ingest --doi "10.1109/DAC63849.2025.11132862" --project "MyResearch"
zotero-ingest --paper-url "https://www.usenix.org/conference/osdi25/presentation/lou" --venue "OSDI 2025" --project "MyResearch"

# Or specify venue explicitly (still normalised to DBLP convention)
zotero-ingest --doi "10.1109/DAC63849.2025.11132862" --venue "ASPLOS" --project "MyResearch"

# Documentation/webpage items bypass magic-wand identifier lookup
zotero-ingest \
  --webpage-url "https://doc.dpdk.org/guides/prog_guide/ring_lib.html" \
  --title "DPDK Programmer's Guide: Ring Library" \
  --author "DPDK Project" \
  --project "MyResearch" \
  --tag dpdk --tag ring-buffer

# Direct PDF documentation can be attached explicitly
zotero-ingest \
  --webpage-url "https://doc.dpdk.org/guides/prog_guide/ring_lib.html" \
  --title "DPDK Programmer's Guide: Ring Library" \
  --attach-url "https://fast.dpdk.org/doc/pdf-guides/prog_guide-20.08.pdf" \
  --project "MyResearch"

Note that metadata and pdf collection uses the built-in magic wand and Find Full Text functionality, which maybe paywalled or not depending on your network. For documentation or project websites, use --webpage-url instead; it creates an explicit Zotero webpage item and does not try identifier/magic-wand ingest.

CLI collection export

Export a collection into an importable directory or zip package:

zotero-export --collection "cxl-noob" --output cxl-noob-export --zip
zotero-export --collection-id 37 --output cxl-noob-export.zip --zip --overwrite

The package includes:

• collection.rdf with Zotero RDF metadata and child notes
• collection.bib and collection.ris fallback exports
• attachments/ with copied attachment files when available
• manifest.json with item and attachment metadata

For Zotero RDF packages, copied attachment paths are added to the RDF so another Zotero client can import collection.rdf together with the adjacent files.

API overview

Items

Notes

Attachments

Collections

Export

Supported formats: better-bibtex, better-biblatex, bibtex, biblatex, ris, csl-json, csv, zotero-rdf, tei, cff.

# Better BibTeX with notes
bib = bridge.export.item(item_id, format="better-bibtex", options={"exportNotes": True})

# Full collection as RIS
ris = bridge.export.collection(collection_id, format="ris")

# Importable collection package with notes and attachments
manifest = bridge.export.collection_package(
    collection_id,
    "cxl-noob-export.zip",
    zip_output=True,
    overwrite=True,
)

# Entire library
bib = bridge.export.library(format="better-bibtex")

DBLP venue naming

When the ingestion workflow auto-derives a venue name, it normalises to DBLP convention:

• ISSTA 2023 → issta2023
• ASPLOS 2025, Volume 1 → asplos2025-1
• NeurIPS 2023, Volume 2 → neurips2023-2

A curated mapping of 50+ common venues + DBLP API fallback + local cache handles less common venues automatically.

Requirements

• Python ≥ 3.10
• A running Zotero instance with the debug-bridge extension installed

Releases

Acknowledgements

This SDK is built on top of the Zotero debug-bridge extension by Emile Sonneveld / iris-advies.com, originally distributed as part of the zotero-better-bibtex test fixtures. The debug-bridge enables arbitrary JavaScript execution inside a running Zotero instance via an authenticated HTTP endpoint, which is the foundation of everything this SDK does.

License

MIT