---
name: Pyzotero
slug: pyzotero
category: Automation
description: Pyzotero lets you manage Zotero libraries from Python with the Zotero Web API. Use it to read, create, update, delete, search, and export references, attachments, tags, and collections.
github: "https://github.com/LeonChaoX/qinyan-academic-skills/tree/main/skills/01-%E8%AE%BA%E6%96%87%E6%A3%80%E7%B4%A2%E4%B8%8E%E6%96%87%E7%8C%AE%E7%AE%A1%E7%90%86/pyzotero"
language: Python
stars: 814
forks: 68
install: "npx degit 'https://github.com/LeonChaoX/qinyan-academic-skills/tree/main/skills/01-%E8%AE%BA%E6%96%87%E6%A3%80%E7%B4%A2%E4%B8%8E%E6%96%87%E7%8C%AE%E7%AE%A1%E7%90%86/pyzotero' ~/.claude/skills/pyzotero"
installs_to: ~/.claude/skills/pyzotero
source_path: skills/01-论文检索与文献管理/pyzotero/SKILL.md
collection_size: 25
category_size: 1523
collection_url: "https://dirskills.com/collections/LeonChaoX/qinyan-academic-skills"
added: 2026-08-22T05:22:06.226Z
last_synced: 2026-08-22T05:22:06.226Z
canonical_url: "https://dirskills.com/skills/pyzotero"
---

# Pyzotero

Pyzotero lets you manage Zotero libraries from Python with the Zotero Web API. Use it to read, create, update, delete, search, and export references, attachments, tags, and collections.

**Install:**

```bash
npx degit 'https://github.com/LeonChaoX/qinyan-academic-skills/tree/main/skills/01-%E8%AE%BA%E6%96%87%E6%A3%80%E7%B4%A2%E4%B8%8E%E6%96%87%E7%8C%AE%E7%AE%A1%E7%90%86/pyzotero' ~/.claude/skills/pyzotero
```

## README

# Pyzotero

Pyzotero is a Python wrapper for the [Zotero API v3](https://www.zotero.org/support/dev/web_api/v3/start). 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](references/authentication.md) for full setup details.

## Installation

```bash
uv add pyzotero
# or with CLI support:
uv add "pyzotero[cli]"
```

## Quick Start

```python
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](references/authentication.md) | Credentials, library types, local mode |
| [references/read-api.md](references/read-api.md) | Retrieving items, collections, tags, groups |
| [references/search-params.md](references/search-params.md) | Filtering, sorting, search parameters |
| [references/write-api.md](references/write-api.md) | Creating, updating, deleting items |
| [references/collections.md](references/collections.md) | Collection CRUD operations |
| [references/tags.md](references/tags.md) | Tag retrieval and management |
| [references/files-attachments.md](references/files-attachments.md) | File retrieval and attachment uploads |
| [references/exports.md](references/exports.md) | BibTeX, CSL-JSON, bibliography export |
| [references/pagination.md](references/pagination.md) | follow(), everything(), generators |
| [references/full-text.md](references/full-text.md) | Full-text content indexing and retrieval |
| [references/saved-searches.md](references/saved-searches.md) | Saved search management |
| [references/cli.md](references/cli.md) | Command-line interface usage |
| [references/error-handling.md](references/error-handling.md) | Errors and exception handling |

## Common Patterns

### Fetch and modify an item
```python
item = zot.item('ITEMKEY')
item['data']['title'] = 'New Title'
zot.update_item(item)
```

### Create an item from a template
```python
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
```python
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)
```python
zot = Zotero(library_id='123456', library_type='user', local=True)
items = zot.items()
```