Repository navigation
Description
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
.venvcreated byuv - 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.pyActual 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.pyResult:
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_ENVto be set, or- an explicit
python-interpreter-pathoverride
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.pyResult:
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.pyResult:
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.pyResult:
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.
Activity
[-]Pyrefly 1.0.0 does not auto-detect project-root .venv unless VIRTUAL_ENV is set[/-][+]Pyrefly 1.0.0 does not auto-detect project-root .venv when .venv is a symlink[/+]firegate22 commentedon May 19, 2026
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 commentedon May 19, 2026
Thank you for the thorough report, @iotakappa.
Looked into how
tyandpyrightsolve this and both avoid the problem architecturally rather than tweaking symlink-follow flags.The structural difference:
Pyrefly's
find_in_rootalready correctly identifies.venvvia thepyvenv.cfgmarker (which works with symlinks sincePath::existsfollows them). The bug is in the second step —find_in_dirthen walks into the venv withwalkdir::follow_links(false)to find the python3 binary, and that walk breaks at the symlink boundary.But that second step is unnecessary. Once
pyvenv.cfgis found, the interpreter location is fixed by venv convention (PEP 405):<venv>/bin/python(orpython3)<venv>/Scripts/python.exePyright (
pythonPathUtils.ts) and ty (site_packages.rs) both construct the interpreter path directly from the standard layout — no walking. Same foruv,pip-tools, andhatch. The marker-file-plus-known-layout approach is symlink-robust by construction.Suggested fix: replace the
find_in_dir(&path)call infind_in_rootwith a direct path construction for the standard venv layout. This:.venv(no walking across the symlink boundary)pyvenv.cfgat runtimefollow_linkstradeoff entirely (no need to choose between breaking normal venvs and supporting symlinked ones)The existing
walk_interpretermachinery 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.13is a symlink chain back to the system Python, and following it loses the venv identity Python needs.Tagging @connernilsen for routing.
sjh9714 commentedon May 20, 2026
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.
Fix symlinked .venv interpreter discovery (pyrefly-org#3509)