Skip to content

fix(windows): don't require symlinks for the runtime venv - #4509

Open
aignas wants to merge 22 commits into
bazel-contrib:mainfrom
aignas:fix.aignas.windows-no-symlinks
Open

aignas wants to merge 22 commits into
bazel-contrib:mainfrom
aignas:fix.aignas.windows-no-symlinks

Conversation

@aignas

@aignas aignas commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

On Windows, py_binary and py_test create a venv at runtime by
symlinking the interpreter, its .dll files and the site-packages
files into a temporary directory. Without the privilege to create
symlinks, this fails with WinError 1314, which is the default for
users that can't enable Developer Mode.

On Windows, if creating a symlink fails, the bootstrap now uses hard
links for files, junctions for directories, and copies if those aren't
possible, e.g. when the temporary directory is on a different volume.
The runfiles files are already copies when Bazel can't create symlinks,
so they aren't moved, as that would break the next run that uses the
same runfiles tree. Other platforms are unchanged.

Windows refuses to delete read-only files, such as hard links to Bazel
outputs, and the read-only attribute is shared by all the hard links of
a file, so the venv's read-only files are deleted with
FILE_DISPOSITION_FLAG_IGNORE_READONLY_ATTRIBUTE instead of clearing
the attribute. This needs Windows 10 1809 or Windows Server 2019, so
older versions still require the privilege to create symlinks.

The RULES_PYTHON_TESTING_DISABLE_SYMLINKS environment variable forces
the fallback on Windows, which a new test uses, and a new CI job uses
to build and test examples/bzlmod with --nowindows_enable_symlinks.

Fixes #3792

If creating a symlink fails, e.g. on Windows without the privilege to
create symlinks, the venv that is created at runtime uses hard links,
junctions or copies instead, and its pyvenv.cfg sets home, because
Python can't find it from the interpreter otherwise.

The RULES_PYTHON_TESTING_DISABLE_SYMLINKS environment variable forces
the fallback, so that it can be tested where symlinks work.
@aignas

aignas commented Nov 15, 2026

Copy link
Copy Markdown
Collaborator Author

This PR was written by an AI agent (Claude Code) working for @aignas. Review comments are read and addressed by the agent, and every reply and change is reviewed and approved by @aignas before it is posted or pushed.

The new Windows CI job is experimental: it checks whether examples/bzlmod builds and passes without symlinks, so this stays a draft until it's green.

This comment was generated by an AI agent and approved by @aignas.

Revert this before the PR leaves draft.
On Windows, the venv paths are Windows paths, which the bash checks
couldn't handle.
Use the `? "--flag"` keys that presubmit_test requires, and download
the remote cache outputs, because without symlinks Bazel creates a
junction in the runfiles tree for an output that isn't downloaded yet.
@aignas

aignas commented Nov 15, 2026

Copy link
Copy Markdown
Collaborator Author

I am not sure if it is the smallest possible change to fix the issue, but it is pretty small and if it works, I'll be chuffed.

The fallback for when symlinks can't be created is now Windows only.

Windows refuses to delete a read-only file and the attribute is shared
by all the hard links of a file, so removing the venv made the hard
linked Bazel outputs writable. The hard links are now removed first, and
the attribute is restored on their originals.
Instead of restoring the read-only attribute of hard linked Bazel
outputs after clearing it, delete the read-only files of the venv with
FILE_DISPOSITION_FLAG_IGNORE_READONLY_ATTRIBUTE, which doesn't change
the other hard links of a file. It needs Windows 10 1809 or Windows
Server 2019, so older versions still require symlinks.

@rickeylev rickeylev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Several lines in the PR description reach 73–76 columns, exceeding the
72-column limit for merge commit messages in .editorconfig.

Suggested fix: Re-wrap the PR description body at 72 columns while preserving
the existing wording.

This is an agent-generated comment reviewed and approved by the user.

Comment thread tests/bootstrap_impls/BUILD.bazel Resolved
… globals

Move them next to the other top-level globals and use a lower case name
for the one that changes at runtime.
When Bazel could create the runfiles symlinks, but the venv falls back
to hard links, os.link() hard linked the symlink itself, so
sys.executable was still a symlink. Resolve the target first.
When processes share RULES_PYTHON_EXTRACT_ROOT, another one can create
the entry between the existence check and creating the link, which
made the fallback copy onto it. Also only catch OSError from
_winapi.CreateJunction, which every supported Python on Windows has.
They were set up again for every read-only file that is removed. Also
declare the return type of CloseHandle.
The fallback creates junctions for directories, and islink() is False
for them, so a dangling one wasn't removed and makedirs() failed.
Remove the CR of the Windows output, so that the check that the venv was
removed doesn't always pass, follow the runfiles symlinks when looking
for read-only outputs and require that there are some, create the venvs
under TEST_TMPDIR, and quote the paths.
…oved

Check the behavior of lexists(), exists() and unlink() for a dangling
junction, which the bootstrap relies on, and run the cached venv test
with the fallback for when symlinks can't be created.
…ed venv test

Windows can't delete a hard link to a running executable, so cleaning
up the temporary directory failed after the fallback hard linked
sys.executable into the venv. The venv isn't run, so link to a
stand-in file instead.
@aignas
aignas enabled auto-merge November 17, 2026 07:31

@rickeylev rickeylev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM in concept. If we can't create symlinks at build time, then we don't have much choice but to copy at build time, or do something at runtime. The runtime option is cheaper, so I'm in favor of that.

I suppose we could experiment with more exotic strategies, too. e.g. a custom importer, patching rpath on the interpreter, etc. Windows might be a decent place to prove that out, since our build time options are limited.

Pass `--test_env=RULES_PYTHON_TESTING_DISABLE_SYMLINKS=1` in
`build_flags` too and share the mapping with `test_flags` via a YAML
anchor so `bazel test` reuses the build step's analysis cache.
@aignas
aignas added this pull request to the merge queue Nov 19, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

py_binary no longer runs on Windows with rules_python 2.0.0+ using default Windows settings

2 participants