pypa/pip · error · CommandError

--refresh-package option requires 1 argument.

Error message

--refresh-package option requires 1 argument.

What it means

Raised by _handle_refresh_package() in cmdoptions.py:1008 when the value passed to --refresh-package starts with a dash ('-'), which optparse would interpret as another option rather than a package name argument. This guard prevents silent mis-parsing of the option's argument.

Source

Thrown at src/pip/_internal/cli/cmdoptions.py:1008

    help="Disable the cache.",
)

no_deps: Callable[..., Option] = partial(
    Option,
    "--no-deps",
    "--no-dependencies",
    dest="ignore_dependencies",
    action="store_true",
    default=False,
    help="Don't install package dependencies.",
)


def _handle_refresh_package(
    option: Option, opt_str: str, value: str, parser: OptionParser
) -> None:
    if value.startswith("-"):
        raise CommandError("--refresh-package option requires 1 argument.")

    existing: set[str] = getattr(parser.values, option.dest)

    new = value.split(",")
    while ":all:" in new:
        existing.clear()
        existing.add(":all:")
        del new[: new.index(":all:") + 1]
        if ":none:" not in new:
            return

    for name in new:
        if name == ":none:":
            existing.clear()
        else:
            existing.add(canonicalize_name(name))

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Provide an actual package name: `pip install --refresh-package numpy numpy`.
2. Use the `=` syntax: `pip install --refresh-package=numpy numpy`.
3. For multiple packages: `pip install --refresh-package=numpy,scipy numpy scipy`.

Example fix

# before
pip install --refresh-package -v numpy

# after
pip install --refresh-package=numpy numpy

def validate_refresh_package_value(value):
    """Ensure --refresh-package value doesn't start with a dash."""
    if value.startswith('-'):
        raise ValueError(f'--refresh-package requires a package name, got: {value}')
    return value

from pip._internal.exceptions import CommandError
try:
    # pip install --refresh-package ...
except CommandError as e:
    if '--refresh-package' in str(e) and 'requires 1 argument' in str(e):
        # fix the argument and retry

When it happens

Trigger: Calling `pip install --refresh-package -v numpy` (where -v is mistaken for a package name) or `pip install --refresh-package --something numpy`. The callback at cmdoptions.py:1007 checks if value.startswith('-').

Common situations: Missing package name after --refresh-package and the next flag gets consumed as its argument. Shell quoting issues. Typos in package names that start with a dash. Copy-paste errors in scripts.

Related errors

• Cannot use '--only-dependencies' in combination with {confli
• When restricting platform and interpreter constraints using
• Can not use any platform or abi specific options unless inst
• Platform and interpreter constraints using --python-version,
• --build-constraint cannot be used with --no-build-isolation.

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