pip install "file:// does not appear to be a Python project" in CI

By Kaveh Alemi·Latchkey

pip was asked to install a local path (., a directory, or a file:// URL) but found no pyproject.toml or setup.py there. Without project metadata, pip has nothing to build or install.

What this error means

pip fails with "ERROR: file:///home/runner/work/app/app does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found".

ERROR: file:///home/runner/work/app/app does not appear to be a Python project:
neither 'setup.py' nor 'pyproject.toml' found.

Diagnose it: which interpreter and which environment?

which -a python python3 pip
python -c "import sys; print(sys.executable); print(sys.version)"
python -c "import sys; [print(p) for p in sys.path]"
pip list 2>/dev/null | head -20

Common causes

The install path is the wrong directory

pip ran from (or was pointed at) a directory above or beside the project, where no pyproject.toml/setup.py exists.

A monorepo subproject was not targeted

The package lives in a subdirectory, but pip was given the repo root, which has no project metadata.

How to fix it

Install from the directory that has the metadata

1. Confirm where pyproject.toml or setup.py lives.
2. Run pip from that directory or pass its path explicitly.
3. Re-run the install.

pip install ./packages/app

Add a build configuration if it is missing

If the directory is meant to be installable, give it a pyproject.toml with a build backend.

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"

How to prevent it

• Run pip install from the directory holding the project metadata.
• In monorepos, target the specific package path.
• Keep a valid [build-system] in each installable package.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation