{"record":{"id":"7774e4399ed1477c","repo":"Graphify-Labs/graphify","slug":"watchdog-not-installed-run-pip-install-watchdog","errorCode":null,"errorMessage":"watchdog not installed. Run: pip install watchdog","messagePattern":"watchdog not installed\\. Run: pip install watchdog","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"graphify/watch.py","lineNumber":1838,"sourceCode":"\n\ndef watch(watch_path: Path, debounce: float = 3.0) -> None:\n    \"\"\"\n    Watch watch_path for new or modified files and auto-update the graph.\n\n    For code-only changes: re-runs AST extraction + rebuild immediately (no LLM).\n    For doc/paper/image changes: writes a needs_update flag and notifies the user\n    to run /graphify --update (LLM extraction required).\n\n    debounce: seconds to wait after the last change before triggering (avoids\n    running on every keystroke when many files are saved at once).\n    \"\"\"\n    try:\n        from watchdog.observers import Observer\n        from watchdog.observers.polling import PollingObserver\n        from watchdog.events import FileSystemEventHandler\n    except ImportError as e:\n        raise ImportError(\"watchdog not installed. Run: pip install watchdog\") from e\n\n    last_trigger: float = 0.0\n    pending: bool = False\n    changed: set[Path] = set()\n\n    # Load .graphifyignore patterns ONCE at startup so the handler does not\n    # re-parse the file on every filesystem event. Watchdog's handler runs on\n    # the observer thread and is invoked for every event the OS delivers\n    # (Time Machine writes, Docker/Colima VM I/O, Spotlight indexing, …) —\n    # without this short-circuit a busy volume can saturate a CPU core\n    # discarding events one extension at a time. (gh-928)\n    watch_root_for_ignore = watch_path.resolve()\n    ignore_patterns = _load_graphifyignore(\n        watch_root_for_ignore,\n        gitignore=_read_build_gitignore(watch_path / _GRAPHIFY_OUT),\n    )\n\n    class Handler(FileSystemEventHandler):","sourceCodeStart":1820,"sourceCodeEnd":1856,"githubUrl":"https://github.com/Graphify-Labs/graphify/blob/7fe58b0b0f3873be9a21c30106b8b8527c353aa6/graphify/watch.py#L1820-L1856","documentation":"graphify's live-watch feature (watch_for_changes / watch in graphify/watch.py) depends on the third-party 'watchdog' package to observe filesystem events. The function imports watchdog.observers lazily and converts an ImportError into a plain, actionable ImportError telling you to pip-install it. It fires only when the watchdog dependency is absent from the active interpreter, not when watching itself fails.","triggerScenarios":"Calling graphify.watch.watch_for_changes(...) (or any CLI path that starts a file watcher) in an environment where `import watchdog` raises ImportError. The try block imports watchdog.observers.Observer, PollingObserver, and watchdog.events.FileSystemEventHandler; any failure of that import chain triggers the re-raise.","commonSituations":"Installing graphify without its watch extras, using a different virtualenv/interpreter than the one where watchdog was installed, or a CI container that never installs optional filesystem-watching dependencies.","solutions":["Install the dependency into the interpreter graphify runs under: pip install watchdog","If graphify is a dependency of your project, add watchdog to your project's dependencies (or graphify's watch extra) so it is installed automatically","Verify the right environment: `python -m pip show watchdog` using the same python that runs graphify (e.g. graphify-out/.graphify_python)","If you do not need live watching, skip the watch API entirely — extraction and clustering do not require watchdog"],"exampleFix":"# before\ngraphify.watch.watch_for_changes(Path('.'), callback)  # ImportError: watchdog not installed\n\n# after\n# shell:\n#   pip install watchdog\ngraphify.watch.watch_for_changes(Path('.'), callback)","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec('watchdog') is None:\n    raise SystemExit('watchdog missing — pip install watchdog before enabling live watch')\n\ngraphify.watch.watch_for_changes(Path('.'), callback=on_change, debounce=2.0)","typeGuard":null,"tryCatchPattern":"try:\n    graphify.watch.watch_for_changes(Path('.'), callback=on_change)\nexcept ImportError as e:\n    if 'watchdog' in str(e):\n        print('live watch disabled: install watchdog to enable')\n    else:\n        raise","preventionTips":["Declare watchdog as a dependency of any project that uses graphify's watch API","Pin/check optional extras at environment setup time (pip check / requirements lock) so the import cannot fail at runtime","Gate watch features behind a config flag so systems without watchdog degrade to manual /graphify --update runs"],"tags":["python","dependencies","import-error","filesystem-watcher"],"backgroundTag":null,"analyzedSha":"7fe58b0b0f3873be9a21c30106b8b8527c353aa6","analyzedAt":"2026-08-14T19:23:21.323Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}