Using the python package manager "uv" for Blender Extensions

I’ve built a dependency install/uninstall panel for my Blender extensions using the python package manager “uv”, with plain pip as an automatic fallback.
Here’s a demo on how it looks in action. (Note that you have to install uv first to get that speed)
It’s now shipping in three of my extensions: marimo-blender, jupyter-blender, and the nodebpy extension.
Reusing this in your own extension

If you’d like to add the same dependency installer to your own Blender extension, the blueprint below was generated with Claude Fable. Paste it into Claude Code or another coding agent inside your repository and let it implement the feature.
blueprint-dependency-installer.md
# Blueprint: Python Dependency Installer Panel for Blender Extensions

A step-by-step implementation guide for an agent. Following it adds a
production-quality dependency installer to a Blender extension: a sidebar
panel that installs/uninstalls pip packages into Blender's extension
site-packages, using `uv` when available (10–100× faster than pip), with a
UI that stays responsive during and after operations.

Reference implementations (all three follow this blueprint):

- `marimo-blender/marimo_blender/` — `addon_setup.py`, `preferences.py`
- `jupyter-blender/jupyter_blender/` — same files, multiple top-level deps
- `nodebpy_extension/nodebpy_export/` — same files, no server component

If one of these repos is available, prefer copying from it and adapting;
this document explains every piece so you can also build from scratch and
review the result.

---

## Feature summary

- **Install button** in a sidebar panel installs a declared dependency set
  into the extension's site-packages (`pip install --target`), preferring
  `uv` with a plain-pip fallback. Output streams line-by-line into a
  collapsible log box.
- **Uninstall button** removes the dependencies *and their entire
  transitive closure* — but only distributions actually installed in the
  target directory, so packages belonging to other extensions survive.
- **Live status**: per-module ✓/✗ list, "Processing …" while running,
  "Done with code: N" after. All of it updates instantly, even when
  Blender's UI is idle.
- **Install greys out** once everything is installed. **Uninstall greys
  out** while an operation runs (and while any server/kernel that uses the
  packages is running).
- Everything runs in daemon threads; Blender never blocks.

## Architecture

Two files:

```
my_extension/
├── addon_setup.py    # Executor (thread/subprocess runner) + Installer + module-level singleton
└── preferences.py    # Operators (thin wrappers) + draw function + thread-safe redraw helper
```

- `Executor` — runs a function or a subprocess in a daemon thread, with a
  `line_callback(str)` per stdout line and a `finally_callback(executor)`
  when done. Tracks `is_running` and `exit_code`.
- `Installer(Executor)` — a **module-level singleton** (`installer =
  Installer()`); owns the dependency list, the cached installed-state map,
  and the install/uninstall/list command construction.
- Operators call `installer.<operation>(line_callback=…,
  finally_callback=…)` and return `{'FINISHED'}` immediately.
- A `draw_*` function renders the panel; it runs on **every UI redraw**,
  which drives several design constraints below.

---

## Step 1 — `addon_setup.py`: the Executor

```python
import importlib.machinery
import importlib.metadata
import importlib.util
import logging
import os
import re
import shutil
import subprocess
import sys
import threading
import traceback
from typing import Any, Callable, Optional


def _invoke_callback(callback: Optional[Callable], *args: Any) -> None:
    if callback is None:
        return
    try:
        callback(*args)
    except Exception as exc:
        logging.exception("Callback failed:", exc_info=exc)


class Executor:
    """Run a function or a subprocess in a daemon thread, with a
    line-by-line stdout callback and a finally callback."""

    def __init__(self) -> None:
        self._is_running = False
        self._return_value: Any = None
        self._exception: Optional[Exception] = None
        self._process: Optional[subprocess.Popen] = None
        self._exit_code = -1
        self._command_line = ""

    def exec_function(self, function, *args,
                      line_callback=None, finally_callback=None) -> None:
        def _run_background() -> None:
            try:
                self._return_value = function(*args)
            except Exception as exception:
                self._exception = exception
                self.write_exception(exception, line_callback=line_callback)
            finally:
                self._is_running = False
                _invoke_callback(finally_callback, self)

        self._is_running = True
        self._return_value = None
        self._exception = None
        threading.Thread(target=_run_background, daemon=True).start()

    @staticmethod
    def write_exception(exception, line_callback=None) -> None:
        if exception is None:
            return
        for line in (l for f in traceback.format_exception(exception)
                     for l in f.splitlines()):
            _invoke_callback(line_callback, line)

    def exec_command(self, *args, env=None,
                     line_callback=None, finally_callback=None) -> None:
        if self.is_running:
            raise ValueError(f"Process is running: pid={self._process.pid}")

        self._exit_code = -1
        self._command_line = " ".join(args)
        self._process = subprocess.Popen(
            args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, env=env
        )

        def _enqueue_output() -> None:
            encoding = sys.getdefaultencoding()
            stream = self._process.stdout
            while self._process.poll() is None:
                for buffer in iter(stream.readline, b""):
                    _invoke_callback(line_callback,
                                     buffer.decode(encoding).rstrip())
            stream.close()
            self._exit_code = self._process.poll()
            self._process = None

        self.exec_function(_enqueue_output, finally_callback=finally_callback)

    @property
    def is_running(self) -> bool:
        return self._is_running

    @property
    def exit_code(self) -> int:
        return self._exit_code
```

## Step 2 — the Installer: dependency declaration and cached status

Adapt `dependencies` to the extension. Entries may carry version specs
(`"marimo>=0.23,<0.24"`); if a dist name differs from its importable
module name (e.g. `jupyter-client` → `jupyter_client`), add a
`_DIST_TO_MODULE` mapping and route the `find_spec` argument through it.

```python
class Installer(Executor):
    dependencies: list[str] = [
        "YOUR_PACKAGE>=X.Y,<X.Z",   # pin if your code targets a specific API
    ]

    def __init__(self) -> None:
        super().__init__()
        self._modules_cache: Optional[dict[str, bool]] = None

    def get_required_modules(self) -> dict[str, bool]:
        """Map each required dist to whether its module is importable.

        Cached: the panel calls this on every redraw, and probing the
        filesystem per redraw makes the whole UI sticky once site-packages
        is populated. Install/uninstall completion invalidates the cache.
        """
        if self._modules_cache is None:
            importlib.invalidate_caches()
            self._modules_cache = {
                name: importlib.machinery.PathFinder.find_spec(name) is not None
                for name in (
                    re.split(r"[<>=!~\s\[]", d, maxsplit=1)[0]
                    for d in self.dependencies
                )
            }
        return self._modules_cache

    def invalidate_modules_cache(self) -> None:
        self._modules_cache = None

    def _invalidating(self, finally_callback):
        """Wrap a finally_callback so completion refreshes the cache."""
        def _finally(executor):
            self.invalidate_modules_cache()
            _invoke_callback(finally_callback, executor)
        return _finally
```

**Why each piece (do not "simplify" these away):**

- **Cache** — `draw()` runs on every mouse move over the panel and once
  per streamed log line. An uncached filesystem probe (`pkgutil
  .iter_modules()` is the classic mistake — it scans every `sys.path`
  directory) costs ~5 ms per redraw once ~100 packages are installed and
  makes the whole UI feel sticky *forever after install*.
- **`PathFinder.find_spec`, not `importlib.util.find_spec`** — the latter
  answers from `sys.modules` first, so a package that was imported and
  then uninstalled still reads "installed" until Blender restarts. The UI
  must flip to ✗ right after uninstall.
- **`importlib.invalidate_caches()` before probing** — `FileFinder`
  caches directory listings; without this, a *just-installed* package can
  read as missing for a moment.
- **Regex name parsing** — handles `pkg>=1,<2`, `pkg[extra]==1`,
  `pkg~=2.0`, and plain names. A naive `d.split(">=")[0]` breaks the day
  someone adds a version pin.

## Step 3 — the uv/pip machinery (install)

```python
    @staticmethod
    def _site_packages_path() -> Optional[str]:
        return next((p for p in sys.path if p.endswith("site-packages")), None)

    @staticmethod
    def _importable_uv_has_binary() -> bool:
        """An importable ``uv`` module can exist while its binary is
        missing (a prior ``pip install --target uv`` whose scripts never
        landed where ``find_uv_bin`` looks). Such a uv must not be used."""
        try:
            import uv
            uv.find_uv_bin()
            return True
        except Exception:
            return False

    @staticmethod
    def _find_system_uv() -> Optional[str]:
        """Locate a ``uv`` binary, tolerating a GUI-launched Blender's PATH.

        ``shutil.which`` only searches ``os.environ["PATH"]``. When Blender
        is launched from Finder/Dock, macOS gives it a minimal PATH that
        omits Homebrew/cargo/uv-installer dirs (those are added by shell
        startup files). Probe the common locations directly.
        """
        found = shutil.which("uv")
        if found:
            return found
        exe = "uv.exe" if os.name == "nt" else "uv"
        for directory in (
            "/opt/homebrew/bin",                      # Homebrew, Apple Silicon
            "/usr/local/bin",                         # Homebrew Intel / manual
            os.path.expanduser("~/.local/bin"),       # uv's own installer
            os.path.expanduser("~/.cargo/bin"),       # cargo install uv
        ):
            path = os.path.join(directory, exe)
            if os.path.isfile(path) and os.access(path, os.X_OK):
                return path
        return None

    @classmethod
    def _uv_command(cls) -> Optional[list[str]]:
        system_uv = cls._find_system_uv()
        if system_uv:
            return [system_uv]
        if (importlib.util.find_spec("uv") is not None
                and cls._importable_uv_has_binary()):
            return [sys.executable, "-m", "uv"]
        return None

    @classmethod
    def _describe_installer(cls) -> str:
        system_uv = cls._find_system_uv()
        if system_uv:
            return f"Using system uv: {system_uv}"
        if cls._uv_command() is not None:
            return f"Using bundled uv: {sys.executable} -m uv"
        return f"No usable uv found — falling back to pip: {sys.executable} -m pip"

    @staticmethod
    def _subprocess_env(site_packages_path):
        """PYTHONPATH pointing at the target dir — needed both so a
        bundled ``python -m uv`` can import itself from there, and so the
        pip-fallback *uninstall* can find the distributions (see Step 4)."""
        if not site_packages_path:
            return None
        env = dict(os.environ)
        existing = env.get("PYTHONPATH", "")
        env["PYTHONPATH"] = (site_packages_path + os.pathsep + existing
                             if existing else site_packages_path)
        return env

    def _run_command_chain(self, commands, env, line_callback, finally_callback):
        """Run subprocess commands sequentially, aborting if one fails.
        ``finally_callback`` fires exactly once."""
        if not commands:
            _invoke_callback(finally_callback, self)
            return
        head, *tail = commands

        def _after(executor):
            if executor.exit_code != 0:
                _invoke_callback(finally_callback, executor)
                return
            self._run_command_chain(tail, env, line_callback, finally_callback)

        self.exec_command(*head, env=env, line_callback=line_callback,
                          finally_callback=_after)

    def _install_commands(self, packages, target_option):
        uv = self._uv_command()
        if uv is not None:
            return [[*uv, "pip", "install",
                     "--python", sys.executable, *target_option, *packages]]
        commands = []
        if importlib.util.find_spec("pip") is None:
            commands.append([sys.executable, "-m", "ensurepip"])
        commands.append([sys.executable, "-m", "pip", "install",
                         *target_option, "--disable-pip-version-check",
                         "--no-input", *packages])
        return commands

    def install_python_modules(self, line_callback=None, finally_callback=None):
        site_packages_path = self._site_packages_path()
        target_option = (["--target", site_packages_path]
                         if site_packages_path else [])
        missing = [name for name, installed
                   in self.get_required_modules().items() if not installed]
        if not missing:
            missing = list(self.dependencies)  # reinstall → still gives log feedback
        _invoke_callback(line_callback, self._describe_installer())
        self._run_command_chain(
            self._install_commands(missing, target_option),
            self._subprocess_env(site_packages_path),
            line_callback,
            self._invalidating(finally_callback),   # ← refresh cache when done
        )
```

Notes:

- `sys.executable` inside modern Blender points at the **bundled Python
  binary**, not the Blender executable — safe to pass to `--python` and to
  spawn as `python -m pip`.
- Every mutating operation's `finally_callback` **must** go through
  `self._invalidating(...)` — that's the sole cache-refresh trigger.

## Step 4 — proper uninstall (the part everyone gets wrong)

Four separate bugs to avoid, all present in naive implementations:

1. **`pip uninstall` in a bare subprocess finds nothing.** The packages
   live in the extension's `--target` site-packages, which only Blender
   adds to `sys.path` at runtime. Fix: put that dir on the subprocess's
   `PYTHONPATH` (pip then locates and removes them via their `RECORD`) —
   or better, use `uv pip uninstall --target <dir>`, which addresses the
   directory explicitly.
2. **Uninstalling only the top-level dists leaves orphans.** Installing
   `marimo` pulls ~25 transitive packages; jupyterlab pulls ~100.
   Compute the dependency closure and remove all of it.
3. **Blindly wiping the target dir destroys other extensions' packages.**
   The extensions site-packages is *shared*. Restrict the closure to
   distributions actually installed there, seeded only from your roots.
4. **Deleting files doesn't unload the packages from the running
   interpreter.** An already-imported package stays in `sys.modules`, so
   `import jupyterlab` keeps working after uninstall until Blender
   restarts — and worse, a re-install keeps serving the stale in-memory
   modules instead of the fresh code. Purge the removed dists' modules
   from `sys.modules` *before* the uninstall subprocess runs (while each
   dist's file list is still on disk to map dist names → module names).

```python
    @staticmethod
    def _canonical(name: str) -> str:
        return re.sub(r"[-_.]+", "-", name).lower()

    def _target_removal_set(self, site_packages_path) -> list[str]:
        """Our dependencies plus their transitive requirements, restricted
        to distributions actually installed in the target site-packages."""
        if not site_packages_path:
            return []
        in_target = {}
        for dist in importlib.metadata.distributions(path=[site_packages_path]):
            name = dist.metadata["Name"]
            if name:
                in_target[self._canonical(name)] = (name, dist)

        stack = [self._canonical(re.split(r"[<>=!~\s\[]", d, maxsplit=1)[0])
                 for d in self.dependencies]
        seen, removal = set(), []
        while stack:
            key = stack.pop()
            if key in seen or key not in in_target:
                continue
            seen.add(key)
            name, dist = in_target[key]
            removal.append(name)
            for req in dist.requires or []:
                stack.append(self._canonical(
                    re.split(r"[<>=!~;\s\[(]", req, maxsplit=1)[0]))
        return removal

    def _unload_target_modules(self, site_packages_path, packages,
                               line_callback=None) -> None:
        """Purge the removed distributions' modules from ``sys.modules``.

        Must run *before* the uninstall subprocess, while each dist's
        file list / ``top_level.txt`` is still on disk."""
        removal = {self._canonical(p) for p in packages}
        top_level = set()
        for dist in importlib.metadata.distributions(path=[site_packages_path]):
            name = dist.metadata["Name"]
            if not name or self._canonical(name) not in removal:
                continue
            text = dist.read_text("top_level.txt")
            if text:
                top_level.update(l.strip() for l in text.splitlines() if l.strip())
                continue
            # Wheels built with hatchling/flit ship no top_level.txt; derive
            # the importable names from the installed file list instead.
            for file in dist.files or []:
                root = file.parts[0]
                if root in ("..", "__pycache__") or root.endswith(
                        (".dist-info", ".data")):
                    continue
                if root.endswith(".py"):
                    top_level.add(root[:-3])
                elif root.endswith((".so", ".pyd")):
                    top_level.add(root.split(".", 1)[0])
                elif "." not in root:
                    top_level.add(root)

        prefix = os.path.realpath(site_packages_path) + os.sep
        unloaded = 0
        for module_name in list(sys.modules):
            if module_name.split(".", 1)[0] not in top_level:
                continue
            origin = getattr(sys.modules[module_name], "__file__", None)
            if origin and not os.path.realpath(origin).startswith(prefix):
                continue  # same name, but imported from outside the target
            del sys.modules[module_name]
            unloaded += 1
        if unloaded:
            _invoke_callback(line_callback,
                f"Unloaded {unloaded} module(s) from the running interpreter.")

    def uninstall_python_modules(self, line_callback=None, finally_callback=None):
        site_packages_path = self._site_packages_path()
        packages = self._target_removal_set(site_packages_path)
        if not packages:
            _invoke_callback(line_callback, "No installed dependencies to remove.")
            self.invalidate_modules_cache()
            _invoke_callback(finally_callback, self)
            return

        self._unload_target_modules(site_packages_path, packages, line_callback)
        _invoke_callback(line_callback, self._describe_installer())
        uv = self._uv_command()
        if uv is not None:
            commands = [[*uv, "pip", "uninstall",
                         "--python", sys.executable,
                         "--target", site_packages_path, *packages]]
        else:
            # pip has no --target for uninstall; PYTHONPATH (via
            # _subprocess_env) lets it find the dists installed there.
            commands = [[sys.executable, "-m", "pip", "uninstall",
                         "--yes", *packages]]
        self._run_command_chain(
            commands,
            self._subprocess_env(site_packages_path),
            line_callback,
            self._invalidating(finally_callback),
        )
```

Notes:

- `importlib.metadata.distributions(path=[dir])` scopes discovery to that
  one directory — this is what makes the closure surgical.
- Canonical names (`PyYAML` → `pyyaml`, `svg.path` → `svg-path`): dist
  names in `Requires-Dist` don't match `metadata["Name"]` casing/spelling
  exactly, so compare canonicalized, but pass the original names to the
  uninstall command.
- Known, accepted over-approximation: `Requires-Dist` environment markers
  and extras aren't evaluated, so an extras-only dep is removed *if it
  happens to be installed in the target dir*. Fine in practice.
- `uv pip uninstall` takes no `--yes` (it never prompts); pip needs it.
- Module names ≠ dist names (`python-dateutil` installs `dateutil`), so
  `_unload_target_modules` reads each dist's `top_level.txt` — or, for
  hatchling/flit wheels that don't ship one, derives the importable names
  from the dist's file list. The `__file__`-prefix guard keeps a module of
  the same name alone if it was actually imported from outside the target
  dir (e.g. a stdlib or system-site copy).
- Unloading only drops the `sys.modules` entries; objects already holding
  references keep working, which is exactly what you want — nothing
  running crashes, but the next `import` resolves fresh (or fails, once
  the files are gone).
- End the file with the singleton: `installer = Installer()`.

## Step 5 — `preferences.py`: thread-safe redraw

**The single most impactful UX fix.** Callbacks fire on worker threads. A
worker calling `region.tag_redraw()` only marks the region dirty — it does
**not wake Blender's event loop**. With an idle UI (mouse still, no timers
running), the "Done" state renders only on the next input event, so
completion *appears* to take 1–5 s (until the user happens to move the
mouse) when the actual work took 0.3 s. Also never capture
`context.region` into a worker thread — the pointer can dangle.

```python
import bpy
from . import addon_setup

_LINES: list[str] = []


def _lines_append(line: str) -> None:
    # \r-prefixed lines overwrite the previous entry (pip's progress-bar trick).
    if line.startswith("\r") and len(_LINES) > 0:
        del _LINES[-1]
        line = line[1:]
    _LINES.append(line)


def _tag_redraw_panels() -> None:
    """Tag every area hosting this panel. Main thread only.
    ADAPT: match your panel's bl_space_type; add 'PREFERENCES' if the
    draw function also renders in the addon preferences window."""
    for wm in bpy.data.window_managers:          # not bpy.context — timers
        for window in wm.windows:                # have a restricted context
            for area in window.screen.areas:
                if area.type == "VIEW_3D":       # ← your panel's space type
                    for region in area.regions:
                        if region.type == "UI":
                            region.tag_redraw()
    return None


def _request_redraw(*_args) -> None:
    """Thread-safe redraw request. Registering a bpy.app.timers callback
    is thread-safe, wakes the event loop immediately, and runs the tagging
    on the main thread. is_registered coalesces bursts of log lines into a
    single pending redraw."""
    try:
        if not bpy.app.timers.is_registered(_tag_redraw_panels):
            bpy.app.timers.register(_tag_redraw_panels, first_interval=0.0)
    except ValueError:
        pass  # lost a register race with another worker thread — fine
```

Every operator then looks like:

```python
class InstallPythonModules(bpy.types.Operator):
    """Install the Python dependencies"""
    bl_idname = "my_extension.install_python_modules"
    bl_label = "Install Python Modules"
    bl_options = {"REGISTER", "INTERNAL"}

    @classmethod
    def poll(cls, context):
        return not addon_setup.installer.is_running

    def execute(self, context):
        _LINES.clear()
        addon_setup.installer.install_python_modules(
            line_callback=lambda line: _lines_append(line) or _request_redraw(),
            finally_callback=_request_redraw,
        )
        return {"FINISHED"}
```

Create the same thin wrappers for **Uninstall** and **List** (calling
`uninstall_python_modules` / `list_python_modules`). Optionally an
**InstallPythonModule** operator with a `module_name: StringProperty` for
ad-hoc `pip install <name>` (calls `install_python_module`, same pattern —
add that method to Installer mirroring `install_python_modules` with
`module_name.split()` as the package list).

**Uninstall poll guard**: if the extension runs a server/kernel that
imports the packages, block uninstall while it's up:

```python
    @classmethod
    def poll(cls, context):
        # Blocked while the server runs: uninstalling would pull the
        # files out from under the live process.
        return (not addon_setup.installer.is_running
                and not addon_setup.server.is_running)   # if a server exists
```

## Step 6 — the draw function

```python
def draw_dependencies(layout, prefs):
    modules = addon_setup.installer.get_required_modules()   # cached — cheap
    all_installed = all(modules.values())

    header, body = layout.panel("my_extension_dependencies",
                                default_closed=all_installed)
    header.label(text="Dependencies",
                 icon="CHECKMARK" if all_installed else "ERROR")
    if body is None:
        return

    install_row = body.row()
    install_row.alert = not all_installed        # red while missing
    install_row.enabled = not all_installed      # greyed once installed
    install_row.operator(InstallPythonModules.bl_idname, icon="PREFERENCES")

    body.label(text="Required Python Modules:")
    flow = body.row(align=True).grid_flow(align=True)
    for name, is_installed in modules.items():
        flow.row().label(text=name,
                         icon="CHECKMARK" if is_installed else "ERROR")

    row = body.row()
    row.operator(UninstallPythonModules.bl_idname, text="Uninstall")
    row.operator(ListPythonModules.bl_idname, text="List Modules")

    # Collapsible log box
    col = body.column(align=False)
    log_row = col.row(align=True)
    log_row.prop(prefs, "show_logs",
                 icon="TRIA_DOWN" if prefs.show_logs else "TRIA_RIGHT",
                 icon_only=True, emboss=False)
    log_row.label(text="Logs")
    exit_code = addon_setup.installer.exit_code
    if addon_setup.installer.is_running:
        log_row.label(text="Processing ...", icon="SORTTIME")
    elif exit_code >= 0:
        log_row.label(text=f"Done with code: {exit_code}",
                      icon="CHECKMARK" if exit_code == 0 else "ERROR")
    if prefs.show_logs:
        box = col.box().column(align=True)
        for line in _LINES:
            box.label(text=line)
```

The AddonPreferences class needs `show_logs: bpy.props.BoolProperty
(default=False)` (plus `module_name: StringProperty` if you added the
ad-hoc install row). Buttons that require the dependencies (start server,
export, …) get `row.enabled = all_installed`.

---

## Verification checklist

Run these before declaring done:

1. **Compile**: `python3 -m py_compile addon_setup.py preferences.py`.
2. **Closure dry run** (no Blender needed — addon_setup must import
   cleanly without `bpy`, keep it stdlib-only at module level):
   install a root package into a scratch dir with
   `uv pip install --python <blender-python> --target <scratch> <root>`,
   plus one unrelated package; load the module standalone with
   `importlib.util.spec_from_file_location` and assert
   `Installer()._target_removal_set(scratch)` contains the root + its
   deps and **excludes** the unrelated package. Also assert
   `_target_removal_set(None) == []`.
3. **Cache**: first `get_required_modules()` call < 1 ms, repeat calls
   ~0 ms; `invalidate_modules_cache()` → recompute gives the same result.
4. **uv command shape**: round-trip
   `uv pip install --python <py> --target <dir> six` then
   `uv pip uninstall --python <py> --target <dir> six`; dir is empty
   (except uv's `.lock`) afterwards.
5. **Unload dry run** (same scratch setup as #2): import the installed
   packages, call
   `_unload_target_modules(scratch, packages, print)`, and assert no
   `sys.modules` entry with those top-level names remains; after deleting
   the scratch dir and `importlib.invalidate_caches()`, a fresh
   `import` must raise `ImportError`.
6. **In Blender**: install → button greys out and ✓s appear *without
   moving the mouse*; uninstall → ✗s and re-enabled Install button appear
   immediately; log lines stream live during install. After uninstall,
   `import <root>` in Blender's Python console fails right away — no
   restart needed.

## Pitfall index (what breaks if you deviate)

| Deviation | Symptom |
|---|---|
| Uncached module probe in `draw()` | Whole UI sticky after install, forever |
| `importlib.util.find_spec` for status | Uninstall doesn't flip UI until Blender restarts |
| No `importlib.invalidate_caches()` | Fresh install briefly shows as missing |
| Worker thread calls `region.tag_redraw()` | "Done" appears 1–5 s late, only on mouse move |
| Capturing `context.region` into a thread | Dangling pointer if layout changes mid-operation |
| Bare `pip uninstall` subprocess | "Package not installed" — removes nothing |
| Uninstalling only top-level dists | Dozens of orphaned packages accumulate |
| Wiping the target dir | Destroys other extensions' packages (shared dir) |
| No `sys.modules` purge on uninstall | Package still importable until restart; re-install serves stale code |
| Unloading *after* the subprocess | Dist file lists already deleted — nothing to map dist → module names |
| `shutil.which("uv")` only | Dock-launched Blender misses uv → silent slow-pip fallback |
| Trusting an importable `uv` module | `python -m uv` crashes with UvNotFound when the binary is absent |
| `d.split(">=")` name parsing | Breaks on `pkg[extra]`, `pkg~=`, `pkg<`, spaces |
| No uninstall guard while server runs | Files pulled out from under a live kernel |