Skip to content

Instantly share code, notes, and snippets.

@sachajw

sachajw/ZOTERO_SYNCTHING_SETUP.md

Created August 22, 2025 17:21
Show Gist options
  • Save sachajw/47b68ba4757d05fa819d0ed268d02977 to your computer and use it in GitHub Desktop.
Save sachajw/47b68ba4757d05fa819d0ed268d02977 to your computer and use it in GitHub Desktop.
Download ZIP
Sync Zotero between two Macs with Syncthing
Raw
ZOTERO_SYNCTHING_SETUP.md

Syncing Zotero Between Two Computers Using SyncThing

This guide shows you how to sync Zotero's PDF attachments and files between two computers (macOS or Windows) using SyncThing while keeping the database sync through Zotero's built-in service.

Prerequisites

  • Two computers (macOS/Windows) on the same local network
  • Zotero installed on both machines
  • SyncThing installed on both machines

Overview

We'll use a hybrid approach:

  • SyncThing: Syncs PDF files and attachments (storage/ folder)
  • Zotero Sync: Syncs database, references, collections, and metadata

This prevents database corruption while providing fast local file sync.

Step 1: Install Required Software

Install Zotero

  1. Download from zotero.org
  2. Install on both Macs
  3. Create a Zotero account if you don't have one

Install SyncThing

macOS:

  1. Download from syncthing.net

  2. Or install via Homebrew:

    brew install syncthing

Windows:

  1. Download from syncthing.net

  2. Or install via Chocolatey:

    choco install syncthing

  3. Or install via Scoop:

    scoop install syncthing

  4. Install on both computers

Step 2: Configure Zotero Sync

Do this on both computers:

  1. Open Zotero
  2. Go to Zotero → Preferences (or Zotero → Settings)
  3. Click the Sync tab
  4. Enter your Zotero username and password
  5. IMPORTANT: Under "File Syncing", UNCHECK BOTH:
    • "Sync attachment files in My Library using Zotero" (or WebDAV)
    • "Sync attachment files in group libraries using Zotero Storage"
  6. Click OK

Step 3: Locate Zotero Data Directory

On both computers, find your Zotero data directory:

  1. In Zotero, go to Zotero → Preferences → Advanced → Files and Folders
  2. Note the "Data Directory Location"

Default locations:

macOS:

~/Zotero
# Full path: /Users/[username]/Zotero

Windows:

%USERPROFILE%\Zotero
# Full path: C:\Users\[username]\Zotero

Note: This is different from browser profiles:

  • macOS: ~/Library/Application Support/Zotero
  • Windows: %APPDATA%\Zotero

Step 4: Set Up SyncThing

On the First Computer (Primary)

  1. Start SyncThing:

macOS/Linux:

syncthing

Windows:

syncthing.exe
  1. Open your browser and go to: http://localhost:8384
  2. Note your Device ID (displayed on the main page)

On the Second Computer

  1. Start SyncThing (same commands as above)
  2. Open your browser and go to: http://localhost:8384
  3. Click "Add Remote Device"
  4. Enter the Device ID from the first computer
  5. Give it a name (e.g., "Work Laptop" or "Home Desktop")
  6. Click "Save"

Back on the First Computer

  1. You'll see a notification about a new device
  2. Click "Add" to accept the connection
  3. Give the second computer a name
  4. Click "Save"

Step 5: Configure Folder Sync

On the Primary Computer

  1. In SyncThing web interface, click "Add Folder"
  2. Set the following:
    • Folder Label: "Zotero Storage"
    • Folder ID: "zotero-storage" (or any unique ID)
    • Folder Path:
      • macOS: /Users/[your-username]/Zotero/storage
      • Windows: C:\Users\[your-username]\Zotero\storage
    • Or browse to your Zotero data directory and select the storage folder
  3. Under "Sharing", select your second computer
  4. Click "Save"

On the Second Computer

  1. You'll receive a notification about a shared folder
  2. Click "Add" to accept
  3. IMPORTANT: Set the folder path to your local Zotero storage directory:

macOS:

/Users/[your-username]/Zotero/storage

Windows:

C:\Users\[your-username]\Zotero\storage
  1. Click "Save"

Step 6: Optional - Sync Citation Styles

To keep citation styles consistent across both machines:

Repeat Step 5 but for the styles folder:

  • Folder Path:
    • macOS: /Users/[your-username]/Zotero/styles
    • Windows: C:\Users\[your-username]\Zotero\styles
  • Folder ID: "zotero-styles"

Step 7: Clean Destination Machine (Optional)

If you need to start with a completely clean slate on the destination computer:

Option 1: Clean Zotero Data Only (Recommended)

Remove just the Zotero data directory:

macOS:

rm -rf ~/Zotero

Windows:

rmdir /s "%USERPROFILE%\Zotero"

This removes your entire Zotero library, attachments, and database while keeping Zotero installed.

Option 2: Reset Zotero Completely

Remove both data and application settings:

macOS:

# Remove main data directory
rm -rf ~/Zotero

# Remove application profile/preferences
rm -rf ~/Library/Application\ Support/Zotero

# Remove Zotero preferences
rm -rf ~/Library/Preferences/org.zotero.zotero.plist

Windows:

# Remove main data directory
rmdir /s "%USERPROFILE%\Zotero"

# Remove application profile/preferences
rmdir /s "%APPDATA%\Zotero"

Option 3: Clean Storage Folder Only

If you only want to clean attachments but keep your database:

macOS:

rm -rf ~/Zotero/storage/*

Windows:

del /s /q "%USERPROFILE%\Zotero\storage\*"

After cleaning:

  1. Restart Zotero on the destination computer
  2. Sign in to your Zotero account to sync the database
  3. Follow Step 8 below to seed the storage files

Step 8: Speed Up Initial Sync (Optional)

If you already have a large Zotero library with attachments, seed the destination to save time:

  1. Close Zotero on both computers
  2. On your primary computer (with existing library), compress the storage folder:

macOS:

cd ~/Zotero
tar -czf zotero-storage-seed.tar.gz storage/

Windows:

cd "%USERPROFILE%\Zotero"
tar -czf zotero-storage-seed.tar.gz storage

Note: Windows 10/11 includes tar. For older Windows, use 7-Zip or WinRAR

  1. Copy this file to your second computer via USB drive, network share, or cloud storage
  2. On the second computer, extract to the Zotero directory:

macOS:

cd ~/Zotero
tar -xzf zotero-storage-seed.tar.gz

Windows:

cd "%USERPROFILE%\Zotero"
tar -xzf zotero-storage-seed.tar.gz
  1. Now set up SyncThing - it will only need to sync differences instead of all files
  2. Clean up the temporary file:

macOS:

rm zotero-storage-seed.tar.gz

Windows:

del zotero-storage-seed.tar.gz

Step 9: Test the Setup

  1. Close Zotero on both computers
  2. Wait for SyncThing to complete initial sync (check web interface)
  3. Open Zotero on one computer
  4. Add a new item with a PDF attachment
  5. Wait a few minutes for sync
  6. Open Zotero on the second computer
  7. The reference should appear (via Zotero sync) with the PDF attachment (via SyncThing)

Step 10: Set SyncThing to Start Automatically

macOS

Using System Preferences:

  1. Go to System Preferences → Users & Groups → Login Items
  2. Click the + button
  3. Navigate to SyncThing application and add it

Using Homebrew Services:

brew services start syncthing

Windows

Using Task Scheduler:

  1. Open Task Scheduler (Win + R, type taskschd.msc)
  2. Click "Create Basic Task"
  3. Name: "SyncThing"
  4. Trigger: "When I log on"
  5. Action: "Start a program"
  6. Program: Path to syncthing.exe
  7. Finish

Using Startup Folder:

  1. Press Win + R, type shell:startup

  2. Create a batch file syncthing.bat:

    @echo off
start /min syncthing.exe

  3. Place the batch file in the startup folder

Best Practices

  1. Keep both computers online: SyncThing needs both devices online to sync
  2. Close Zotero before major changes: When reorganizing large collections, close Zotero on one computer
  3. Monitor sync status: Check SyncThing web interface if files aren't syncing
  4. Regular backups: SyncThing is not a backup solution - maintain separate backups

Troubleshooting

Files not syncing

  • Check both computers are online and SyncThing is running
  • Verify folder paths are correct in SyncThing
  • Check for sufficient disk space

Database conflicts

  • This shouldn't happen with this setup since we only sync files
  • If it does, check that Zotero file sync is disabled

SyncThing not connecting

  • Ensure both devices are on the same network
  • Check firewall settings
  • Restart SyncThing on both machines

Storage folder not found

  • Verify Zotero data directory location in Zotero preferences
  • Check folder permissions
  • Ensure the storage folder exists (create by adding an attachment in Zotero)

Benefits of This Setup

  • ✅ Free: No storage limits unlike Zotero's paid plans
  • ✅ Fast: Local network speeds for large PDFs
  • ✅ Private: Files stay on your local network
  • ✅ Reliable: Uses Zotero's proven database sync
  • ✅ Safe: No risk of database corruption

Security Notes

  • Files are encrypted in transit between your computers
  • No data leaves your local network (except Zotero database sync)
  • Consider enabling device authentication in SyncThing for additional security

Need help? Check the SyncThing documentation or Zotero forums.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment