fix(cli): don't self-upgrade uv tool installs on Windows by jaeminbird · Pull Request #5149 · github/spec-kit

jaeminbird · 2026-10-28T07:57:50Z

Description

On Windows, specify self upgrade on a uv tool install runs uv tool install --force from inside that tool environment. uv deletes Lib\site-packages, then fails on Scripts\ because the running python.exe is locked, leaving specify without its package; the "Try again" hint can't work after that.

When the running interpreter is a uv tool env on Windows (os.name == "nt" and uv-receipt.toml in sys.prefix), the command now makes no changes and prints the uv command to run once specify exits: the fail-closed fallback from the bug assessment. A hand-off after exit can't stop the next specify launch from re-locking the env and can't report uv's result; microsoft/conductor#171 landed on the same approach. pipx, POSIX, already-latest and invalid-tag behaviour unchanged.

Windows 11, uv 0.13.5, isolated UV_TOOL_DIR/UV_TOOL_BIN_DIR, installed from v1.2.2:

main:

> specify self upgrade
error: failed to remove directory `...\uv\tools\specify-cli\Scripts`: Access is denied. (os error 5)
Upgrade failed. Installer exit code: 2.
> specify --version
ModuleNotFoundError: No module named 'specify_cli'

This PR (v1.2.2 + fix):

> specify self upgrade
Not upgrading specify-cli 1.2.2 → v1.2.4: on Windows, uv cannot replace the tool environment specify is running from. No changes were made.
Run it yourself once this command exits:
  uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v1.2.4
> specify --version
specify 1.2.2

Running the printed command (Git Bash, PowerShell 5.1) gives a working 1.2.4.

Testing

Tested locally with uv run specify --help
Ran existing tests with uv sync && uv run pytest
Tested with a sample project (if applicable)

New TestWindowsUvToolEnvironment in tests/specify_cli/test_version_execution.py; command test fails on main, passes w/ fix. Dev HEAD bare upgrade, --tag v1.2.5.dev0, --tag latest, --dry-run and pipx (isolated PIPX_HOME) same before/after; --tag v1.2.4 from dev HEAD breaks the install on main, stopped here. uv run pytest -n auto: Linux py3.14 same 2 root-only failures as main; Windows py3.14 no new failures. uvx ruff@0.15.0 check src tests, markdownlint on docs/upgrade.md: pass.

AI Disclosure

I did not use AI assistance for this contribution
I did use AI assistance (fill in the disclosure below)

AI disclosure: Claude Code (Claude Opus 5.5, default settings, human-supervised) reproduced the bug and wrote the fix and tests (code generation); results verified on Windows 11 as shown above.

`uv tool install --force` deletes the tool environment before reinstalling it. When `specify self upgrade` runs it from that environment on Windows, uv removes Lib\site-packages and then fails on Scripts\ because the running python.exe is locked, leaving `specify` without its package. When the running interpreter is a uv tool environment on Windows, print the uv command to run once specify exits and make no changes. pipx installs and other platforms are unchanged. Fixes github#5141 Assisted-by: Claude Code (model: Claude Opus 5.5, supervised)

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

Copilot

🟡 Changes recommended

The review found an issue that should be addressed before approval.

2 open issues

This guard runs only when the upgrade really happens. --dry-run returns earlier (lines 104-114),… · New
With this branch, uv-tool installs on Windows are no longer upgraded automatically: the command… · New

_{Review effort: Max}

mnriem · 2026-10-28T14:11:46Z

Please address Copilot feedback

On Windows, a real `specify self upgrade` from a uv tool environment prints the uv command instead of running it, but `--dry-run` still listed that command as the one that would be executed. Preview the same outcome, printing the command to run once specify exits exactly as the real run does, and add the Windows exception to the `--help` text. Refs github#5141 Assisted-by: Claude Code (model: Claude Opus 5.5, supervised)

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

jaeminbird · 2026-10-28T17:54:55Z

@mnriem Addressed both Copilot points in dcc351b:

--dry-run on a Windows uv tool install no longer lists the uv tool install command as one that would run. It prints the same "Run it yourself once this command exits" command as a real run, with dry-run tests.
specify self upgrade --help now mentions the Windows uv tool exception.

Copilot

🟡 Changes recommended

The upgrade guidance omits a warning to stop all processes using the uv tool environment, so following the printed command can still encounter Windows file locks and partially delete the installation.

1 open issue

Warn users to stop processes before running uv · New

2 resolved since last review

With this branch, uv-tool installs on Windows are no longer upgraded automatically: the command…
This guard runs only when the upgrade really happens. --dry-run returns earlier (lines 104-114),…

_{Review effort: Max}

+            "running from. No changes were made.",
+            soft_wrap=True,
+        )
+        console.print("Run it yourself once this command exits:", soft_wrap=True)


mnriem · 2026-10-28T18:35:53Z

Please address Copilot feedback

Exiting `specify self upgrade` does not release the Windows lock on the tool environment's python.exe if another process from it is still running, such as an editor's `specify mcp` server. Running the printed uv command then fails partway through the same way. Say to stop those processes first, in both the real run and --dry-run output and in docs/upgrade.md. Refs github#5141 Assisted-by: Claude Code (model: Claude Opus 5.5, autonomous)

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

jaeminbird · 2026-10-29T06:08:31Z

@mnriem Addressed the remaining Copilot point in 68e38e9: the Windows uv tool guidance (real run, --dry-run, and docs/upgrade.md) now says to stop other specify processes such as specify mcp before running the uv command.

Posted on behalf of @jaeminbird by Claude Code (Claude Opus 5.5, autonomous); the fix, tests and this comment are agent-authored.

Copilot

🔵 Needs a closer look

Human assessment is needed to weigh an unpublished test-coverage gap that could let regressions in Windows uv-tool’s already-current no-op behavior go unnoticed.

1 open issue

Warn users to stop processes before running uv

_{Review effort: Max}

mnriem · 2026-10-29T11:43:51Z

Please address Copilot feedback

jaeminbird requested a review from mnriem as a code owner October 28, 2026 07:57

Copilot AI max review requested due to automatic review settings October 28, 2026 07:57

Copilot AI reviewed Oct 28, 2026

mnriem added the triage-must-have Verdict: high-value, important work for Spec Kit — do first label Oct 28, 2026

mnriem requested a max review from Copilot October 28, 2026 13:45

Copilot started reviewing on behalf of mnriem October 28, 2026 13:45

View session

Copilot AI reviewed Oct 28, 2026

View reviewed changes

Comment thread src/specify_cli/selfs/command_upgrade.py

Comment thread src/specify_cli/selfs/command_upgrade.py

mnriem added the author-awaiting Waiting on author response label Oct 28, 2026

Copilot AI max review requested due to automatic review settings October 28, 2026 17:51

Copilot AI reviewed Oct 28, 2026

mnriem requested a max review from Copilot October 28, 2026 18:17

Copilot started reviewing on behalf of mnriem October 28, 2026 18:17

View session

Copilot AI reviewed Oct 28, 2026

View reviewed changes

Comment thread src/specify_cli/selfs/command_upgrade.py Outdated

"running from. No changes were made.",

soft_wrap=True,

)

console.print("Run it yourself once this command exits:", soft_wrap=True)

Copilot AI max review requested due to automatic review settings October 29, 2026 06:05

Copilot AI reviewed Oct 29, 2026

mnriem requested a max review from Copilot October 29, 2026 11:17

Copilot started reviewing on behalf of mnriem October 29, 2026 11:17

View session

Copilot AI reviewed Oct 29, 2026

View reviewed changes

Navigation Menu

Repository navigation

fix(cli): don't self-upgrade uv tool installs on Windows - #5149

fix(cli): don't self-upgrade uv tool installs on Windows#5149
jaeminbird wants to merge 3 commits into
github:mainfrom
jaeminbird:fix/5141-windows-uv-tool-self-upgrade

jaeminbird commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

jaeminbird commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

jaeminbird commented Oct 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Oct 29, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jaeminbird commented Oct 28, 2026

Description

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

jaeminbird commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

jaeminbird commented Oct 29, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

mnriem commented Oct 29, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants