Zotfix repairs linked attachment paths in your Zotero database so they match your collection folder structure. It is designed for people who use Zotmoov to keep PDFs in a synced folder (OneDrive/Google Drive/etc.). When you reorganize your Zotero collections, the linked attachment paths are not updated automatically — Zotfix fixes that.

• Finds linked attachments (linkMode = 2) in zotero.sqlite
• Builds the expected folder path from your Zotero collection hierarchy
• Moves files into the correct folder (optional; dry-run by default)
• Updates the itemAttachments.path values to the new attachments: paths
• Backs up the database before applying changes

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Always close Zotero before running this tool.

Dry run (default, safe preview):

python zotero_reorganiser.py --base-dir "/path/to/linked/attachments"

Apply changes (moves files + updates DB):

python zotero_reorganiser.py --base-dir "/path/to/linked/attachments" --apply

If your Zotero database is in a non-default location:

python zotero_reorganiser.py --db "/path/to/zotero.sqlite" --base-dir "/path/to/linked/attachments"

• --base-dir / --path (required): The folder containing your collection subfolders
• --db: Path to zotero.sqlite (default: ~/Zotero/zotero.sqlite)
• --apply: Perform moves + update database (disables dry-run)
• --dry-run: Force preview mode
• --interactive / --no-interactive: Prompt when duplicate filenames are found
• --unfiled-dir-name: Folder name for items not in any collection (default _Unfiled)

1. Use Zotmoov to create linked attachments inside your synced folder.
2. Reorganize your Zotero collections as desired.
3. Run Zotfix in dry-run mode to preview changes.
4. Re-run with --apply to update the paths.
5. (Optional) Convert linked files back to Zotero Storage if desired.

To quickly inspect attachment paths:

python inspect_zotero_paths.py --db "/path/to/zotero.sqlite" --limit 20

• The database is backed up before any changes are applied.
• Dry-run mode is the default to prevent accidental moves.
• Keep your synced folder and Zotero database backed up before running.

This project is licensed under the GNU GPLv3. See LICENSE.

Issues and pull requests are welcome. Please include clear reproduction steps and example outputs from a dry run when reporting problems.