facebook / facebook/pyrefly

Pyrefly reports `missing-import` for workspace package exposed via `.pth` editable install

Open
#3,553 5 comments 1 reaction 0 assignees View on GitHub
help wanted language-server stale
Dominant language
Rust
Stars
7k
Forks
516
PR merge metrics
No merged PRs in 30d

Description

### Describe the Bug

Pyrefly fails to resolve imports for a workspace package that is available at runtime via a `.pth` shim in the project's virtual environment. The project uses `uv` as the package manager/workspace tool. The import that triggered the error in my project was:

- `from shared_core.config import Settings`

Pyrefly's IDE diagnostic shows:

```
Cannot find module `shared_core.config`
Looked in these locations (from default config for project root marked by `packages/google-service/pyproject.toml`):
Import root (inferred from project layout): "packages/google-service/src"
Site package path queried from interpreter: [ ... ]
```

However, importing the same module in the configured venv succeeds:

```
$ d:/Projects/Python/Invoice_Intelligence/.venv/Scripts/python.exe -c "from shared_core.config import Settings; print(Settings.__name__)"
Settings
```

**Steps to reproduce**
1. Create a workspace with sibling packages: `packages/google-service` and `packages/shared-core` (source at `packages/shared-core/src`).
2. Use your workspace tooling or installer to expose `shared-core` in the venv via a `.pth` file (e.g., `.venv/Lib/site-packages/shared_core.pth` pointing to `packages/shared-core/src`).
3. Open `packages/google-service/src/google_service/gmail/core_service.py` which contains `from shared_core.config import Settings` in the editor using Pyrefly LSP.
4. Observe a `missing-import` diagnostic for `shared_core.config` in the editor even though the import succeeds at runtime in the same venv.

**Actual behavior**

Pyrefly's resolver does not follow the `.pth` shim used by the editable/workspace install, so imports provided only via that shim are reported as missing.

**Expected behavior**

Pyrefly should either:

- Respect `.pth` shims found under the configured `site-package-path` during environment autoconfiguration, or
- Clearly document that `.pth` shims are not followed and recommend configuration workarounds, or
- Improve heuristics to detect and include workspace source paths from editable/install wrappers.

**Environment / diagnostics**

- Project: monorepo with per-package `pyproject.toml` files and a repository `.venv`.
- Package manager / workspace tool: `uv` (workspace members configured in the root `pyproject.toml`).
- The venv contains `shared_core.pth` and `shared_core-0.1.0.dist-info`.
- Pyrefly initially searched `packages/google-service/src` and the interpreter site-packages; after adding a `search-path` override in `packages/google-service/pyproject.toml` (pointing to `../shared-core/src`) the missing-import diagnostic for `shared_core.config` disappeared.

**Workarounds**

- Add `search-path = ["src", "../shared-core/src"]` to `[tool.pyrefly]` in `packages/google-service/pyproject.toml` (explicitly include sibling source trees).
- Install the package in the venv as an editable package where the source directory is discoverable without a `.pth` shim.

### Sandbox Link

_No response_

### (Only applicable for extension issues) IDE Information

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.