pypa/pip · error · ValueError

which would be overwritten

Error message

 which would be overwritten

What it means

Raised as ValueError by FileOperator.copy_file when check=True and the destination outfile is a symlink or a non-regular existing file. The library refuses to overwrite such targets to avoid clobbering symlinks or special files during installation. The message is the tail fragment ' which would be overwritten' appended to a descriptive prefix built earlier (e.g. '%s is a symlink').

Solutions

1. Pass check=False only if you are certain overwriting the symlink/special file is safe.
2. Remove or unlink the existing outfile (os.unlink) before copying.
3. Resolve the symlink target first and copy there, or redirect the install to a clean directory.

Example fix

# before
fileop.copy_file(src, dst, check=True)
# after
if os.path.islink(dst) or (os.path.exists(dst) and not os.path.isfile(dst)):
    os.unlink(dst)
fileop.copy_file(src, dst, check=True)

def safe_copy(fileop, src, dst, check=True):
    if os.path.islink(dst) or (os.path.exists(dst) and not os.path.isfile(dst)):
        os.unlink(dst)
    return fileop.copy_file(src, dst, check=check)

def is_regular_or_missing(path: str) -> bool:
    return not os.path.exists(path) or (os.path.isfile(path) and not os.path.islink(path))

try:
    fileop.copy_file(src, dst, check=True)
except ValueError as e:
    if 'would be overwritten' in str(e):
        os.unlink(dst)
        fileop.copy_file(src, dst, check=False)

When it happens

Trigger: Calling FileOperator().copy_file(src, '/path/that/is/symlink', check=True); installing into a venv whose scripts are symlinks; re-running an install where a previous symlinked file now would be replaced by a regular copy.

Common situations: Re-installing into environments that use symlinks (PEP 405 venvs, shared-script layouts); CI caching that leaves symlinks; --target installs over a dir containing symlinks.

Related errors

• file '%r' does not exist
• invalid glob %r: mismatching set marker
• invalid glob %r: recursive glob "**" must be used alone
• path ' ' cannot be absolute
• path ' ' cannot end with '/

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

Appendix: source

Thrown at src/pip/_vendor/distlib/util.py:534

        if not os.path.exists(target):
            return True

        return os.stat(source).st_mtime > os.stat(target).st_mtime

    def copy_file(self, infile, outfile, check=True):
        """Copy a file respecting dry-run and force flags.
        """
        self.ensure_dir(os.path.dirname(outfile))
        logger.info('Copying %s to %s', infile, outfile)
        if not self.dry_run:
            msg = None
            if check:
                if os.path.islink(outfile):
                    msg = '%s is a symlink' % outfile
                elif os.path.exists(outfile) and not os.path.isfile(outfile):
                    msg = '%s is a non-regular file' % outfile
            if msg:
                raise ValueError(msg + ' which would be overwritten')
            shutil.copyfile(infile, outfile)
        self.record_as_written(outfile)

    def copy_stream(self, instream, outfile, encoding=None):
        assert not os.path.isdir(outfile)
        self.ensure_dir(os.path.dirname(outfile))
        logger.info('Copying stream %s to %s', instream, outfile)
        if not self.dry_run:
            if encoding is None:
                outstream = open(outfile, 'wb')
            else:
                outstream = codecs.open(outfile, 'w', encoding=encoding)
            try:
                shutil.copyfileobj(instream, outstream)
            finally:
                outstream.close()
        self.record_as_written(outfile)

View on GitHub (pinned to f399c37189)