pypa/pip · error · CommandError

--refresh-package option requires 1 argument.

Error message

--refresh-package option requires 1 argument.

What it means

Raised as CommandError inside the _handle_refresh_package callback (cmdoptions.py:1008) when the value supplied to --refresh-package starts with a dash. Because optparse passes the next token as the option's value, a leading dash means no real package name was given (the user wrote another flag where the package name should be, or forgot the argument). The callback (lines 1004-1024) otherwise splits comma-separated names and canonicalizes them into the refresh set.

Solutions

1. Supply an explicit package name: `pip install --refresh-package <pkg>`.
2. Use the equals form to avoid ambiguity: `pip install --refresh-package=<pkg>`.
3. Reorder so a real package name immediately follows --refresh-package before any other flags.

Example fix

# before
pip install --refresh-package --no-deps requests
# after
pip install --refresh-package requests --no-deps

# Ensure a real package name follows --refresh-package.
def build_refresh_args(packages):
    out = []
    for p in packages:
        if not p or p.startswith("-"):
            raise ValueError(f"--refresh-package needs a package name, got {p!r}")
        out += ["--refresh-package", p]
    return out

When it happens

Trigger: `pip install --refresh-package --no-deps pkg` (the --no-deps is consumed as the value), or `pip install --refresh-package --user pkg`.

Common situations: Reordering flags on the command line and accidentally placing another option immediately after --refresh-package; using = syntax incorrectly.

Related errors

• Too many arguments
• --build-constraint cannot be used with --no-build-isolation.
• Can not use any platform or abi specific options unless…
• Cannot combine '--path' with '--user' or '--local'
• Cannot use '--only-dependencies' in combination with

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

Appendix: 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 f399c37189)