{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/cli/cmdoptions.py#L990-L1026","documentation":"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.","triggerScenarios":"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('-').","commonSituations":"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.","solutions":["Provide an actual package name: `pip install --refresh-package numpy numpy`.","Use the `=` syntax: `pip install --refresh-package=numpy numpy`.","For multiple packages: `pip install --refresh-package=numpy,scipy numpy scipy`."],"exampleFix":"# before\npip install --refresh-package -v numpy\n\n# after\npip install --refresh-package=numpy numpy","handlingStrategy":"validation","validationCode":"def validate_refresh_package_value(value):\n    \"\"\"Ensure --refresh-package value doesn't start with a dash.\"\"\"\n    if value.startswith('-'):\n        raise ValueError(f'--refresh-package requires a package name, got: {value}')\n    return value","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import CommandError\ntry:\n    # pip install --refresh-package ...\nexcept CommandError as e:\n    if '--refresh-package' in str(e) and 'requires 1 argument' in str(e):\n        # fix the argument and retry\n","preventionTips":["Use = syntax for option values: --refresh-package=numpy.","Double-check that package names don't start with dashes.","Validate CLI arguments before passing them to pip."],"tags":["cli","option-parsing","refresh-package","validation"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}