zotero2readwise 1.4.2

Export your Zotero annotations and notes to Readwise

Zotero ➡️ Readwise

zotero2readwise is a Python library that retrieves all Zotero annotations† and notes. Then, It automatically uploads them to your Readwise§.

This is particularly useful for the new Zotero PDF Reader that stores all highlights in the Zotero database. The new Zotero, also available for iOS app (currently in beta). In the new Zotero, the annotations are NOT saved in the PDF file unless you export the highlights in order to save them.

If you annotate your files outside the new Zotero PDF reader, this library may not work with your PDF annotations as those are not retrievable from Zotero API.

This library is for you if you annotate (highlight + note) using the Zotero's PDF reader (including the Zotero iOS)

👉Updating an existing Zotero annotation or note and re-running this library will update the corresponding Readwise highlight without creating a duplicate!

† Annotations made in the new Zotero PDF reader and note editor.

§ Readwise is a paid service/software that integrates your highlights from almost everywhere (Pocket, Instapaper, Twitter, Medium, Apple Books, and many more). It even has an amazing OCR for directly importing your highlights on a physical book/article into Readwise and allowing you to export all your highlights to Obsidian, Notion, Roam, Markdown, etc. Moreover, It has an automated Spaced Repition and Active Recall.

---

Installation

Using pip (recommended for users)

You can install the library by running:

pip install zotero2readwise

Note: If you do not have pip installed on your system, you can follow the instructions here.

For Development

This project uses uv for dependency management and requires Python 3.12 or higher.

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and setup the repository

git clone https://github.com/e-alizadeh/Zotero2Readwise.git
cd Zotero2Readwise
uv sync --all-extras  # Install all dependencies including dev tools

Run tests

uv run pytest  # Run all tests with coverage

Usage

Since we have to retrieve the notes from Zotero API and then upload them to the Readwise, the minimum requirements are:

• Readwise access token [Required]: You can get your access token from https://readwise.io/access_token
• Zotero API key [Required]: Create a new Zotero Key from your Zotero settings
• Zotero personal or group ID [Required]:
  • Your personal library ID (aka userID) can be found here next to Your userID for use in API calls is XXXXXX.
  • If you're using a group library, you can find the library ID by
    1. Go to https://www.zotero.org/groups/
    2. Click on the interested group.
    3. You can find the library ID from the URL link that has format like https://www.zotero.org/groups/<group_id>/group_name. The number between /groups/ and /group_name is the libarry ID.
• Zotero library type [Optional]: "user" (default) if using personal library and "group" if using group library.

Note that if you want to retrieve annotations and notes from a group, you should provide the group ID (zotero_library_id=<group_id>) and set the library type to group (zotero_library_type="group").

Approach 1 (running a python script)

For this approach you can download run.py script (from here). Run python run.py -h to get more information about all options. You can simply run the script as the following:

python run.py <readwise_token> <zotero_key> <zotero_id>

Approach 2 (through python terminal)

from zotero2readwise.zt2rw import Zotero2Readwise

zt_rw = Zotero2Readwise(
    readwise_token="your_readwise_access_token",  # Visit https://readwise.io/access_token)
    zotero_key="your_zotero_key",  # Visit https://www.zotero.org/settings/keys
    zotero_library_id="your_zotero_id", # Visit https://www.zotero.org/settings/keys
    zotero_library_type="user", # "user" (default) or "group"
    include_annotations=True, # Include Zotero annotations -> Default: True
    include_notes=False, # Include Zotero notes -> Default: False
)
zt_rw.run()

Just to make sure that all files are created, you can run save_failed_items_to_json() from readwise attribute of the class object to save any highlight that failed to upload to Readwise. If a file or more failed to create, the filename (item title) and the corresponding Zotero item key will be saved to a txt file.

zt_rw.readwise.save_failed_items_to_json("failed_readwise_highlights.json")

Approach 3 (through the nix flake)

If you have nix, you can skip any installation and do:

nix run github:e-alizadeh/Zotero2Readwise -- <readwise_token> <zotero_key> <zotero_id>

The text file with failed highlights, which usually would be written to the Zotero2Readwise python package directory, will now be written to you working directory, since nix does not allow writing to package directories. If you don't want this file created, supply --suppress_failures as an additional argument.

---

Automated Sync with GitHub Actions

Set up a scheduled automation once and forget about it!

You can use the Zotero2Readwise-Sync repository that contains a GitHub Actions workflow to automatically sync your Zotero annotations/notes to Readwise on a schedule.

Quick Setup:

1. Fork Zotero2Readwise-Sync
2. Add your secrets in the forked repo's Settings → Secrets:
   • READWISE_TOKEN - Your Readwise access token
   • ZOTERO_KEY - Your Zotero API key
   • ZOTERO_ID - Your Zotero user/library ID
3. The workflow runs automatically on schedule (or trigger manually)

Minimal Workflow Example:

name: Zotero to Readwise Sync

on:
  schedule:
    - cron: "0 3 * * 1"  # Weekly on Monday at 3 AM UTC
  workflow_dispatch:  # Manual trigger

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: astral-sh/setup-uv@v4
      - run: uvx --from zotero2readwise run
        env:
          READWISE_TOKEN: ${{ secrets.READWISE_TOKEN }}
          ZOTERO_KEY: ${{ secrets.ZOTERO_KEY }}
          ZOTERO_LIBRARY_ID: ${{ secrets.ZOTERO_ID }}

Request a new feature or report a bug

Feel free to request a new feature or report a bug in GitHub issue here.

📫 How to reach me: