What causes "{path} is not relative to any discovered {site_type}sites" in python-poetry/poetry?

Pass a relative path (the package subpath, e.g. 'foo/bar.py') instead of an absolute one.

python-poetry/poetry · error · ValueError

{path} is not relative to any discovered {site_type}sites

Error message

{path} is not relative to any discovered {site_type}sites

What it means

Raised as ValueError in SitePackages.make_candidates when an absolute path is passed but it is not relative to any of the discovered site-packages candidate directories (purelib/platlib/fallbacks, or the writable subset). The method requires absolute paths to live under a known site.

Source

Thrown at src/poetry/utils/env/site_packages.py:83

        self._writable_candidates = []
        for candidate in self._candidates:
            if not is_dir_writable(path=candidate, create=True):
                continue
            self._writable_candidates.append(candidate)

        return self._writable_candidates

    def make_candidates(
        self, path: Path, writable_only: bool = False, strict: bool = False
    ) -> list[Path]:
        candidates = self._candidates if not writable_only else self.writable_candidates
        if path.is_absolute():
            for candidate in candidates:
                with contextlib.suppress(ValueError):
                    path.relative_to(candidate)
                    return [path]
            site_type = "writable " if writable_only else ""
            raise ValueError(
                f"{path} is not relative to any discovered {site_type}sites"
            )

        results = [candidate / path for candidate in candidates]

        if not results and strict:
            raise RuntimeError(
                f'Unable to find a suitable destination for "{path}" in'
                f" {paths_csv(self._candidates)}"
            )

        return results

    def distributions(
        self, name: str | None = None, writable_only: bool = False
    ) -> Iterable[metadata.Distribution]:
        path = list(
            map(

View on GitHub (pinned to 92b74dcfe3)

Solutions

Pass a relative path (the package subpath, e.g. 'foo/bar.py') instead of an absolute one.
Ensure the absolute path actually lives under the env's purelib or platlib.
Operate on the correct SitePackages instance for the env that owns the path.
Resolve symlinks first: Path(path).resolve() may reveal the real location under a site dir.

Example fix

// before
site_packages.write_text(Path("/usr/lib/python3.11/site-packages/foo/__init__.py"), "")
# not under this env's sites -> ValueError

// after - relative path under the env's site
site_packages.write_text(Path("foo/__init__.py"), "")

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def path_under_a_site(path: Path, candidates: list[Path]) -> bool:
    p = path.resolve()
    for c in candidates:
        try:
            p.relative_to(c.resolve())
            return True
        except ValueError:
            continue
    return False

# before calling site_packages methods with an absolute path:
assert path_under_a_site(target, site_packages.candidates)

Type guard

def is_not_relative_to_sites(e: Exception) -> bool:
    return isinstance(e, ValueError) and "not relative to any discovered" in str(e)

Try / catch

try:
    site_packages._path_method_wrapper(abs_path, "write_text", data)
except ValueError as e:
    if "not relative to any discovered" in str(e):
        # pass a relative path instead
        site_packages.write_text(rel_path, data)
    else:
        raise

Prevention

Pass relative package subpaths to SitePackages methods, not absolute filesystem paths.
Operate on the SitePackages instance belonging to the env that owns the path.
Resolve symlinks before checking - the real target may sit under a site dir.
Validate path.relative_to(candidate) for at least one candidate before acting.

When it happens

Trigger: Calling make_candidates(path, ...) (or a higher-level SitePackages method that delegates via _path_method_wrapper) with path.is_absolute() True, where path.relative_to(candidate) raises ValueError for every candidate. Exact branch: site_packages.py:77-85.

Common situations: Passing a global system path (/usr/lib/python3.11/...) to a venv-scoped SitePackages; path outside purelib/platlib; passing an absolute path when a relative package path was expected; wrong env's SitePackages instance used.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/6dc0e71126e52429.json. Report an issue: GitHub.