pypa/pip · error · OptionParsingError

Could not split options

Error message

Could not split options: {options_str}

What it means

pip uses shlex.split() to tokenize the options portion of a requirements file line, and it failed with a ValueError. This almost always means there are unbalanced quotes in the options string — shlex cannot close an unterminated quoted segment.

Solutions

1. Check for unbalanced single or double quotes in the options portion of the line
2. Ensure every opening quote has a matching closing quote
3. On Windows, avoid backslashes in paths or escape them properly; prefer forward slashes
4. If the option value has no spaces, you can often drop the quotes entirely

Example fix

# before — requirements.txt
requests --hash="sha256:abc123

# after
requests --hash="sha256:abc123"

import shlex

def validate_options_quoting(line: str) -> bool:
    """Returns True if the options portion of the line has balanced quotes."""
    tokens = line.split(" ")
    options = []
    for t in tokens:
        if t.startswith("-"):
            break
    options_str = " ".join(t for t in tokens if t not in options)
    try:
        shlex.split(options_str)
        return True
    except ValueError:
        return False

import shlex

def has_balanced_quotes(options_str: str) -> bool:
    """Type guard: True if shlex can split the options string without error."""
    try:
        shlex.split(options_str)
        return True
    except ValueError:
        return False

from pip._internal.exceptions import RequirementsFileParseError
from pip._internal.req.req_file import parse_requirements

try:
    list(parse_requirements("requirements.txt", session))
except RequirementsFileParseError as e:
    if "Could not split options" in str(e):
        print("Fix unbalanced quotes in the options portion of the line")
    else:
        raise

When it happens

Trigger: A requirements file line like 'requests --hash="sha256:abc...' where the closing double quote is missing, or '--index-url=\'https://...' with an unterminated single quote. shlex.split raises ValueError and it is wrapped in OptionParsingError then RequirementsFileParseError.

Common situations: Unterminated quotes after editing a hash or URL. Backslash escaping gone wrong in Windows paths. Copy-paste that dropped a trailing quote. Multi-line values that were not properly joined.

Related errors

• Invalid requirement
• recursively references itself in
• Configuration file could not be loaded.\n
• Could not open file
• Error parsing

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

Appendix: source

Thrown at src/pip/_internal/req/req_file.py:442

def get_line_parser(finder: PackageFinder | None) -> LineParser:
    def parse_line(line: str) -> tuple[str, Values]:
        # Build new parser for each line since it accumulates appendable
        # options.
        parser = build_parser()
        defaults = parser.get_default_values()
        defaults.index_url = None
        if finder:
            defaults.format_control = finder.format_control
            defaults.release_control = finder.release_control

        args_str, options_str = break_args_options(line)

        try:
            options = shlex.split(options_str)
        except ValueError as e:
            raise OptionParsingError(f"Could not split options: {options_str}") from e

        opts, _ = parser.parse_args(options, defaults)

        return args_str, opts

    return parse_line


def break_args_options(line: str) -> tuple[str, str]:
    """Break up the line into an args and options string.  We only want to shlex
    (and then optparse) the options, not the args.  args can contain markers
    which are corrupted by shlex.
    """
    tokens = line.split(" ")
    args = []
    options = tokens[:]
    for token in tokens:
        if token.startswith(("-", "--")):

View on GitHub (pinned to f399c37189)