pypa/pip · error · ValueError

path '%s' cannot be absolute

Error message

path '%s' cannot be absolute

What it means

Raised by convert_path() on non-Unix-like systems (where os.sep != '/', e.g. Windows). setup-script filenames are always supplied Unix-style and split on '/', but an absolute path (leading '/') cannot be meaningfully converted to a native path, so a ValueError is raised. On Unix (os.sep == '/') the function returns early and never raises this.

Source

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

        return value


def convert_path(pathname):
    """Return 'pathname' as a name that will work on the native filesystem.

    The path is split on '/' and put back together again using the current
    directory separator.  Needed because filenames in the setup script are
    always supplied in Unix style, and have to be converted to the local
    convention before we can actually use them in the filesystem.  Raises
    ValueError on non-Unix-ish systems if 'pathname' either starts or
    ends with a slash.
    """
    if os.sep == '/':
        return pathname
    if not pathname:
        return pathname
    if pathname[0] == '/':
        raise ValueError("path '%s' cannot be absolute" % pathname)
    if pathname[-1] == '/':
        raise ValueError("path '%s' cannot end with '/'" % pathname)

    paths = pathname.split('/')
    while os.curdir in paths:
        paths.remove(os.curdir)
    if not paths:
        return os.curdir
    return os.path.join(*paths)


class FileOperator(object):

    def __init__(self, dry_run=False):
        self.dry_run = dry_run
        self.ensured = set()
        self._init_record()

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Pass a relative path: convert_path('src/pkg/file.py') instead of '/src/pkg/file.py'.
2. On Windows, rebuild the path relative to the project root before calling convert_path.
3. Avoid feeding os.path.abspath() output into convert_path().

Example fix

// before
convert_path('/src/mypkg/__init__.py')  # on Windows
// after
convert_path('src/mypkg/__init__.py')

import os
def safe_convert_path(p):
    if os.sep != '/' and p.startswith('/'):
        raise ValueError('convert_path received absolute path: %r' % p)
    from distlib.util import convert_path
    return convert_path(p)

from distlib.util import convert_path
try:
    native = convert_path(script_path)
except ValueError as e:
    if 'cannot be absolute' in str(e):
        native = convert_path(os.path.relpath(script_path, project_root))
    else:
        raise

When it happens

Trigger: Calling convert_path('/abs/path/to/file') on Windows, or distutils/setuptools setup() receiving a script/data_file path beginning with '/' while running on Windows.

Common situations: Cross-platform builds where a Linux developer hardcodes an absolute path in setup.py and a Windows CI worker runs the build; packaging scripts that compute paths from os.path.abspath and feed them to convert_path.

Related errors

• path '%s' cannot end with '/'
• Target path exists but is not a directory, will not continue
• {req_name} does not appear to be a Python project: neither '
• Directory {name!r} is not installable. Neither 'setup.py' no
• file '%r' does not exist

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