# pip "error: no such option" - Fix Bad Flags & Wrapped Lines in CI

> Fix pip "error: no such option" in CI - a misspelled flag, an option for the wrong subcommand, or a requirements line option pip does not recognize.

Source: https://latchkey.dev/learn/python/pip-no-such-option  
Updated: 2026-06-25

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.

## 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
```

> Compatible tags decide whether a wheel is usable. A package that installs from a wheel on your machine and builds from source in CI is a tag mismatch, and the resulting failure is a compiler error rather than a pip error.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt