pypa/pip · error · ValueError

which would be overwritten

Error message

 which would be overwritten

What it means

Raised by FileOperator.copy_file() (when check=True, the default) if the destination outfile is a symlink or a non-regular file (e.g. a directory, device, FIFO). Overwriting such a file could follow an unexpected link or clobber a special file, so a ValueError is raised combining the reason ('X is a symlink' / 'X is a non-regular file') with the suffix ' which would be overwritten'.

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 d7d0d0a394)

Solutions

1. Remove or replace the offending destination before copying: if it is a symlink, os.unlink() it first.
2. Pass check=False to copy_file only if you have explicitly verified the destination is safe to overwrite.
3. Audit the install destination for symlinks/special files prior to the copy operation.

Example fix

// before
operator.copy_file(src, dest)  # dest is a symlink
// after
import os
if os.path.islink(dest):
    os.unlink(dest)
operator.copy_file(src, dest)

import os
def safe_copy(operator, src, dst, check=True):
    if check and (os.path.islink(dst) or (os.path.exists(dst) and not os.path.isfile(dst))):
        os.unlink(dst)  # or raise, per policy
    return operator.copy_file(src, dst, check=check)

try:
    operator.copy_file(src, dst)
except ValueError as e:
    if 'would be overwritten' in str(e):
        os.unlink(dst)
        operator.copy_file(src, dst)
    else:
        raise

When it happens

Trigger: operator.copy_file(src, '/path/to/symlink') where the destination is a symlink; copy_file into a path that is currently a directory or FIFO; an existing install left a symlink that a later copy tries to overwrite.

Common situations: Re-installing a package whose console_scripts are symlinks, virtualenv layouts using symlinks for site-packages, or stale special files left in an install prefix.

Related errors

• {req_name} does not appear to be a Python project: neither '
• Directory {name!r} is not installable. Neither 'setup.py' no
• {path} is a symlink; Will not return uid for symlinks
• path '%s' cannot be absolute
• path '%s' cannot end with '/'

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