Skip to content
anonymizer

Troubleshooting

First, run anonymize doctor

Before digging into specific symptoms, run the bundled diagnostic:

Terminal window
anonymize doctor

It checks Python version (needs 3.12 for blis wheels), the installed package, Tesseract OCR readiness, leftover failure state from a previous broken updater run, and the network probe. Exit code 0 if all required checks are green, 1 if something’s wrong — each line shows ✓ / ? / ✗ with the reason. Run with --no-network on offline machines and with --fix to clear stale state.

If doctor is green and you still have a problem, the symptom guides below.

”Tesseract OCR is not installed” / scanned PDF failed

Scanned and hybrid PDFs need local Tesseract with English and Russian language packs. DOCX, XLSX, and PDFs with a normal text layer still work without it, but image-only scanned pages are rejected until OCR is available.

Install Tesseract, then rerun anonymize doctor --no-network:

Terminal window
# macOS
brew install tesseract tesseract-lang


# Ubuntu / Debian
sudo apt install tesseract-ocr tesseract-ocr-eng tesseract-ocr-rus


# Windows PowerShell
winget install UB-Mannheim.TesseractOCR

On Windows, if doctor still reports missing eng or rus, make sure the language data files are present in Tesseract’s tessdata directory and that tesseract.exe is on PATH.

OCR output looks unreliable

Low-quality scans can produce low-confidence OCR. The UI surfaces risky or unsafe warnings for low mean OCR confidence; treat those documents as requiring manual visual review. If OCR produces no text for a page, processing fails instead of silently dropping that page. Try a clearer scan or run the PDF through a dedicated OCR tool first.

The web UI didn’t open

If you ran anonymize and no browser tab appeared:

  1. Look for the printed URL in the terminal (e.g., http://127.0.0.1:54321) and open it manually
  2. If no URL printed, check ~/.anonymizer/logs/<date>.log for errors
  3. On Linux without a default browser, set BROWSER=firefox (or your browser) before running

”Permission denied” during install on macOS/Linux

The install script writes to ~/.local/share/uv/tools/ and ~/.local/bin/. If either is owned by another user (e.g., you sudo-installed something else there once), chown them to your user:

Terminal window
sudo chown -R $USER ~/.local

“Antivirus blocked the install” on Windows

Some AV engines flag fresh Python wheels until they get reputation. Workarounds:

  1. Use the Corporate / offline setup airgap workflow with an explicit allowlist
  2. Add %LOCALAPPDATA%\uv\ to your AV’s exclusion list
  3. Wait — usually reputation builds within a few days of a release

”Update banner won’t go away even after upgrading”

The version check is cached for 60 minutes. To force a recheck, restart anonymize. If the banner persists, check that anonymize --version matches what you expect — there may be two installs on PATH.

”Tokens don’t match between two runs of the same document”

By design. Token numbering is per-session. See Tokens.

Reporting a different problem

If your issue isn’t here, use the Feedback flow.