pypa/pip · error · PreviousBuildDirError

pip can't proceed with requirements

Error message

pip can't proceed with requirements '{self}' due to a pre-existing build directory ({self.source_dir}). This is likely due to a previous installation that failed . pip is being responsible and not assuming it can delete this. Please delete it and try again.

What it means

ensure_pristine_source_checkout (req_install.py:628) raises PreviousBuildDirError when the source_dir already looks installable (is_installable_dir returns true), indicating a prior build left artifacts behind. pip refuses to assume it can safely delete the directory, to avoid version inconsistencies from a half-built tree.

Solutions

1. Delete the stale build/source directory named in the error and retry.
2. Run pip cache purge and pip install --no-cache-dir to avoid reusing tainted dirs.
3. Use a fresh checkout or build in a clean tmp directory.

Example fix

# before (stale dir blocks install)
pip install ./pkg
# after
rm -rf ./pkg/build ./build && pip install ./pkg

# Before installing from a path, ensure no stale build dir exists.
import pathlib, shutil
src = pathlib.Path("./pkg")
for stale in [src / "build", pathlib.Path("build"), src / "pip-build"]:
    if stale.is_dir():
        shutil.rmtree(stale)
        print(f"Removed stale build dir: {stale}")

# When scripting pip, detect PreviousBuildDirError and clean up once.
import subprocess, re, sys
proc = subprocess.run([sys.executable, "-m", "pip", "install", "./pkg"], capture_output=True, text=True)
if "pre-existing build directory" in proc.stderr:
    m = re.search(r"\((.*?)\)", proc.stderr)
    if m:
        import shutil; shutil.rmtree(m.group(1), ignore_errors=True)
    # retry once
    subprocess.check_call([sys.executable, "-m", "pip", "install", "./pkg"])

When it happens

Trigger: A previous pip build/install failed or was interrupted, leaving build artifacts in the unpacked source dir; re-running pip install against the same checkout triggers the check.

Common situations: Interrupted builds in CI with cached source dirs; local dev re-running pip after a failed -e install; stale build/ directories.

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/8d2fbdb865b9e364. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/req/req_install.py:628

                parent_dir,
                autodelete=autodelete,
                parallel_builds=parallel_builds,
            )

    def needs_unpacked_archive(self, archive_source: Path) -> None:
        assert self._archive_source is None
        self._archive_source = archive_source

    def ensure_pristine_source_checkout(self) -> None:
        """Ensure the source directory has not yet been built in."""
        assert self.source_dir is not None
        if self._archive_source is not None:
            unpack_file(str(self._archive_source), self.source_dir)
        elif is_installable_dir(self.source_dir):
            # If a checkout exists, it's unwise to keep going.
            # version inconsistencies are logged later, but do not fail
            # the installation.
            raise PreviousBuildDirError(
                f"pip can't proceed with requirements '{self}' due to a "
                f"pre-existing build directory ({self.source_dir}). This is likely "
                "due to a previous installation that failed . pip is "
                "being responsible and not assuming it can delete this. "
                "Please delete it and try again."
            )

    # For editable installations
    def update_editable(self) -> None:
        if not self.link:
            logger.debug(
                "Cannot update repository at %s; repository location is unknown",
                self.source_dir,
            )
            return
        assert self.editable
        assert self.source_dir
        if self.link.scheme == "file":

View on GitHub (pinned to f399c37189)