From d82dcf5da070a9c8e0195d27066e22c7bb1705d4 Mon Sep 17 00:00:00 2001 From: JoaoMarcos44 Date: Mon, 10 Aug 2026 09:25:55 -0300 Subject: [PATCH] docs(update): document transactional Windows venv recovery (#83149) --- website/docs/getting-started/updating.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md index 3c361adca6..6be78d2673 100644 --- a/website/docs/getting-started/updating.md +++ b/website/docs/getting-started/updating.md @@ -108,6 +108,14 @@ Close the listed processes and re-run. If you're sure the concurrent process won A second, separate guard refuses to touch the venv while any process is running from its Python interpreter (the Desktop app's backend, a gateway, a Python REPL). Those processes keep native extension files (`.pyd`) locked, and a dependency sync that dies partway on an access-denied error strands the install between versions. This guard is **not** bypassed by `--force`; if you're certain the detected holders are false positives, use the explicit `hermes update --force-venv`. +#### Windows venv recreation is transactional + +When the Windows installer must recreate an existing `venv`, it first moves the old directory to a unique `venv.stale.*` name, then creates and verifies the replacement. The old tree is deleted only after `venv\Scripts\python.exe` exists in the new tree. + +If the move cannot be completed, the installer stops and leaves the live `venv` untouched. If `uv` fails or reports success without creating the interpreter, any partial replacement is moved to `venv.failed.*` and the previous venv is restored. This keeps the health and blocker checks usable after a failed install. + +A `venv.stale.*` or `venv.failed.*` directory can remain when another process still owns a file handle. Close Hermes Desktop, gateways, and Python processes using the install, then retry the install/update; parked directories are cleaned up best-effort after a successful recreation. + Expected output looks like: ```