Pyrefly 1.0.0 does not auto-detect project-root .venv when .venv is a symlink

[iotakappa]

Summary

Pyrefly finds the project root correctly, but does not auto-detect a local project .venv. It falls back to /usr/local/bin/python3 and the wrong site-packages unless VIRTUAL_ENV is set explicitly.

This was observed with a uv project, but the issue appears to be about .venv discovery rather than uv itself.

Environment

• Pyrefly: 1.0.0
• VS Code extension: meta.pyrefly-1.0.0-darwin-arm64
• OS: macOS
• Project uses a local .venv created by uv
• Python in .venv: 3.13.2

Project layout

prestanda/
├─ pyproject.toml
├─ repricer.py
└─ .venv/
   ├─ bin/python
   ├─ bin/python3
   └─ pyvenv.cfg

pyproject.toml contains a normal [project] section and no [tool.pyrefly] override.

Reproduction

From the project root:

~/.vscode/extensions/meta.pyrefly-1.0.0-darwin-arm64/bin/pyrefly dump-config repricer.py

Actual result

Pyrefly reports the correct project root, but uses the system interpreter:

Default configuration for project root marked by `/Users/mb/workspace/Documents-python/prestanda/pyproject.toml`
  Using interpreter: /usr/local/bin/python3
  Resolving imports from:
    Import root (inferred from project layout): "/Users/mb/workspace/Documents-python/prestanda"
    Site package path queried from interpreter: ["/Users/mb/Library/Python/3.9/lib/python/site-packages", "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/site-packages"]

This causes missing import errors for packages that are installed only in .venv.

Control experiment

If VIRTUAL_ENV is set, Pyrefly uses the local .venv correctly:

cd /Users/mb/workspace/Documents-python/prestanda
VIRTUAL_ENV="$PWD/.venv" ~/.vscode/extensions/meta.pyrefly-1.0.0-darwin-arm64/bin/pyrefly dump-config repricer.py

Result:

Using interpreter: /Users/mb/workspace/Documents-python/prestanda/.venv/bin/python3
Site package path queried from interpreter: ["/Users/mb/workspace/Documents-python/prestanda/.venv/lib/python3.13/site-packages"]

Expected result

Pyrefly should auto-detect the project-root .venv without requiring:

• VIRTUAL_ENV to be set, or
• an explicit python-interpreter-path override

Additional notes

The project path is symlinked/canonicalized on this machine:

• logical path: /Users/mb/workspace/Documents-python/prestanda
• resolved path: /Users/mb/Documents/python/prestanda

The local virtual environment is also a symlink:

• .venv -> ../../../venv/prestanda
• resolved venv path: /Users/mb/venv/prestanda

However, .venv exists in both the logical and resolved project root, and Pyrefly still falls back to /usr/local/bin/python3 unless VIRTUAL_ENV is set.

Pyrefly also works when the interpreter is passed explicitly via the symlinked path:

~/.vscode/extensions/meta.pyrefly-1.0.0-darwin-arm64/bin/pyrefly dump-config --python-interpreter-path .venv/bin/python3 repricer.py

Result:

Using interpreter: .venv/bin/python3
Site package path queried from interpreter: ["/Users/mb/Documents/python/prestanda/.venv/lib/python3.13/site-packages"]

That suggests the interpreter itself is usable through the symlink, and the failure is specifically in auto-discovery of the project-root .venv.

Minimal control experiment

I also reproduced this outside the project with two minimal throwaway projects that differed only in whether .venv was a real directory or a symlink.

Real .venv project:

/tmp/pyrefly-venv-check-real/
├─ pyproject.toml
├─ app.py
└─ .venv/                  # real directory created with python3 -m venv

Symlinked .venv project:

/tmp/pyrefly-venv-check-link/
├─ pyproject.toml
├─ app.py
└─ .venv -> /tmp/pyrefly-venv-check-real/.venv

Running Pyrefly against the real .venv project:

cd /tmp/pyrefly-venv-check-real
~/.vscode/extensions/meta.pyrefly-1.0.0-darwin-arm64/bin/pyrefly dump-config app.py

Result:

Using interpreter: /private/tmp/pyrefly-venv-check-real/.venv/bin/python3
Site package path queried from interpreter: ["/private/tmp/pyrefly-venv-check-real/.venv/lib/python3.9/site-packages"]

Running Pyrefly against the symlinked .venv project:

cd /tmp/pyrefly-venv-check-link
~/.vscode/extensions/meta.pyrefly-1.0.0-darwin-arm64/bin/pyrefly dump-config app.py

Result:

Using interpreter: /usr/local/bin/python3
Site package path queried from interpreter: ["/Users/mb/Library/Python/3.9/lib/python/site-packages", "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/site-packages"]

This makes the issue reproducible without uv, without the VS Code workspace path symlink, and without any project-specific dependencies. The deciding factor appears to be whether .venv itself is a symlink.

That may or may not be relevant, but it could help narrow down the root cause.

[firegate22]

I hope it's okay, I add my 'case' here though I can't say for sure it's the same underlying issue.
My .venv in the project root is as well a symlink (uv based) venv and it is not recognized by pyrefly.

I can fix this by using [tool.pyrefly] in the pyproject.toml without any configuration (just the header) - at least this works in VS Code + .venv selected as active interpreter via the Python Environments extension.

[NathanTempest]

Thank you for the thorough report, @iotakappa.

Looked into how ty and pyright solve this and both avoid the problem architecturally rather than tweaking symlink-follow flags.

The structural difference:

Pyrefly's find_in_root already correctly identifies .venv via the pyvenv.cfg marker (which works with symlinks since Path::exists follows them). The bug is in the second step — find_in_dir then walks into the venv with walkdir::follow_links(false) to find the python3 binary, and that walk breaks at the symlink boundary.

But that second step is unnecessary. Once pyvenv.cfg is found, the interpreter location is fixed by venv convention (PEP 405):

• POSIX: <venv>/bin/python (or python3)
• Windows: <venv>/Scripts/python.exe

Pyright (pythonPathUtils.ts) and ty (site_packages.rs) both construct the interpreter path directly from the standard layout — no walking. Same for uv, pip-tools, and hatch. The marker-file-plus-known-layout approach is symlink-robust by construction.

Suggested fix: replace the find_in_dir(&path) call in find_in_root with a direct path construction for the standard venv layout. This:

• Works for symlinked .venv (no walking across the symlink boundary)
• Preserves the symlink-prefixed python path that Python needs to find pyvenv.cfg at runtime
• Matches the approach used by every other Python tool that auto-detects venvs
• Sidesteps the follow_links tradeoff entirely (no need to choose between breaking normal venvs and supporting symlinked ones)

The existing walk_interpreter machinery is still useful elsewhere (e.g., finding system Python candidates), but it shouldn't be the mechanism for venv interpreter discovery.

Note: walkdir::follow_links(true) would NOT be a safe alternative — inside a normal venv, bin/python3 → bin/python3.13 → /usr/bin/python3.13 is a symlink chain back to the system Python, and following it loses the venv identity Python needs.

Tagging @connernilsen for routing.

[sjh9714]

I can take a narrow pass at this: add a regression test for a symlinked project-root .venv and update venv discovery to check the standard interpreter paths directly before falling back to the existing walk-based lookup.