{"record":{"id":"05af21916e75f28c","repo":"pypa/pip","slug":"refresh-package-option-requires-1-argument","errorCode":null,"errorMessage":"--refresh-package option requires 1 argument.","messagePattern":"--refresh-package option requires 1 argument\\.","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/cli/cmdoptions.py","lineNumber":1008,"sourceCode":"    help=\"Disable the cache.\",\n)\n\nno_deps: Callable[..., Option] = partial(\n    Option,\n    \"--no-deps\",\n    \"--no-dependencies\",\n    dest=\"ignore_dependencies\",\n    action=\"store_true\",\n    default=False,\n    help=\"Don't install package dependencies.\",\n)\n\n\ndef _handle_refresh_package(\n    option: Option, opt_str: str, value: str, parser: OptionParser\n) -> None:\n    if value.startswith(\"-\"):\n        raise CommandError(\"--refresh-package option requires 1 argument.\")\n\n    existing: set[str] = getattr(parser.values, option.dest)\n\n    new = value.split(\",\")\n    while \":all:\" in new:\n        existing.clear()\n        existing.add(\":all:\")\n        del new[: new.index(\":all:\") + 1]\n        if \":none:\" not in new:\n            return\n\n    for name in new:\n        if name == \":none:\":\n            existing.clear()\n        else:\n            existing.add(canonicalize_name(name))\n\n","sourceCodeStart":990,"sourceCodeEnd":1026,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/cli/cmdoptions.py#L990-L1026","documentation":"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.","triggerScenarios":"`pip install --refresh-package --no-deps pkg` (the --no-deps is consumed as the value), or `pip install --refresh-package --user pkg`.","commonSituations":"Reordering flags on the command line and accidentally placing another option immediately after --refresh-package; using = syntax incorrectly.","solutions":["Supply an explicit package name: `pip install --refresh-package <pkg>`.","Use the equals form to avoid ambiguity: `pip install --refresh-package=<pkg>`.","Reorder so a real package name immediately follows --refresh-package before any other flags."],"exampleFix":"# before\npip install --refresh-package --no-deps requests\n# after\npip install --refresh-package requests --no-deps","handlingStrategy":"validation","validationCode":"# Ensure a real package name follows --refresh-package.\ndef build_refresh_args(packages):\n    out = []\n    for p in packages:\n        if not p or p.startswith(\"-\"):\n            raise ValueError(f\"--refresh-package needs a package name, got {p!r}\")\n        out += [\"--refresh-package\", p]\n    return out","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always place a concrete package name immediately after --refresh-package.","Prefer the = form (--refresh-package=pkg) to avoid optparse value ambiguity."],"tags":["cli-options","refresh-package","arguments","command-error"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}