pip "error: no such option" - Fix Bad Flags & Wrapped Lines in CI
By Daniel Zoghalchali·Latchkey
pip rejected a command-line flag or a requirements-file option it does not recognize. Either the option is misspelled, belongs to a different subcommand, or your pip is too old to know it.
What this error means
pip aborts immediately with error: no such option: --xyz. Nothing installs because pip never parses past the bad option. It can come from the command line or from an option line inside requirements.txt.
pip output
Usage: pip install [options] <requirement specifier> ...
error: no such option: --hash-algorithm
Diagnose it: which Python, and which index?
A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.
Terminal
which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5
Common causes
Misspelled or wrong-subcommand flag
A typo (--no-cache vs --no-cache-dir) or a flag valid for another subcommand (pip download vs pip install) makes pip reject it.
Option unsupported by this pip version
An option added in a newer pip fails on an older one. The CI image’s pip may predate the flag you copied from current docs.
A stray option line in requirements.txt
requirements files accept a limited set of options (--hash, --index-url, -e). An unsupported option on its own line triggers the same error.
How to fix it
Check the option and the subcommand
Run pip install --help (or the relevant subcommand) to confirm the exact flag name.
Make sure the option belongs to the subcommand you are running.
Fix the spelling - many errors are --no-cache vs --no-cache-dir.
Pin a known pip version in CI and check flags against its --help.
Keep requirements-file options to the documented subset.
Upgrade pip early so newer flags are available.
Frequently asked questions
What causes pip "error: no such option"?
There are 3 common causes: misspelled or wrong-subcommand flag, option unsupported by this pip version, and a stray option line in requirements.txt. A typo (--no-cache vs --no-cache-dir) or a flag valid for another subcommand (pip download vs pip install) makes pip reject it.
How do I fix pip "error: no such option"?
There are 2 fixes depending on which cause you have: check the option and the subcommand and upgrade pip if the flag is newer. Work through them in order, since the first is the most common.
What does pip "error: no such option" actually mean?
pip aborts immediately with error: no such option: --xyz.
How do I stop pip "error: no such option" happening again?
Pin a known pip version in CI and check flags against its --help. The prevention section lists 3 changes that keep it from recurring.
