What causes "Invalid dependency specification: {requirement}" in python-poetry/poetry?

Use valid PEP 508 syntax: `poetry add 'requests>=2.31,<3'` (quote the whole spec in the shell).

python-poetry/poetry · error · ValueError

Invalid dependency specification: {requirement}

Error message

Invalid dependency specification: {requirement}

What it means

RequirementsParser.parse raises ValueError when the requirement string cannot be parsed by any strategy — PEP 508, git/url, path, or simple 'name version' form (dependency_specification.py:71-96). It is the catch-all for malformed dependency specifications passed to `poetry add` or the parser API.

Source

Thrown at src/poetry/utils/dependency_specification.py:96

        extras = []
        extras_m = re.search(r"\[([\w\d,-_ ]+)\]$", requirement)
        if extras_m:
            extras = [e.strip() for e in extras_m.group(1).split(",")]
            requirement, _ = requirement.split("[")

        specification = (
            self._parse_url(requirement)
            or self._parse_path(requirement)
            or self._parse_simple(requirement)
        )

        if specification:
            if extras:
                specification.setdefault("extras", extras)
            return specification

        raise ValueError(f"Invalid dependency specification: {requirement}")

    def _parse_pep508(self, requirement: str) -> DependencySpec | None:
        if " ; " not in requirement and re.search(r"@[\^~!=<>\d]", requirement):
            # this is of the form package@<semver>, do not attempt to parse it
            return None

        with contextlib.suppress(ValueError):
            dependency = Dependency.create_from_pep_508(requirement)
            specification: DependencySpec = {}
            specification = dependency_to_specification(dependency, specification)

            if specification:
                specification["name"] = dependency.name
                return specification

        return None

    def _parse_git_url(self, requirement: str) -> DependencySpec | None:

View on GitHub (pinned to 92b74dcfe3)

Solutions

Use valid PEP 508 syntax: `poetry add 'requests>=2.31,<3'` (quote the whole spec in the shell).
For path/url/git deps, use Poetry's table form or `poetry add ./local-pkg` / `git+https://...`.
Remove stray whitespace/punctuation around operators and ensure the package name is valid.

Example fix

// before
poetry add requests >=2.31        # shell splits into two args -> unparseable
// after
poetry add 'requests>=2.31'

Defensive patterns

Strategy: validation

Validate before calling

from packaging.requirements import InvalidRequirement, Requirement
try:
    Requirement(requirement)
except InvalidRequirement:
    raise ValueError(f"Not a valid PEP 508 requirement: {requirement!r}") from None
spec = RequirementsParser(artifact_cache=cache).parse(requirement)

Try / catch

try:
    spec = parser.parse(requirement)
except ValueError as e:
    if "Invalid dependency specification" in str(e):
        log.error("cannot parse requirement %r; use PEP 508 syntax", requirement)
    raise

Prevention

Quote requirement strings on the shell to avoid arg splitting.
Prefer the table form in pyproject.toml for complex deps.
Validate requirements with packaging.Requirement before passing to Poetry.

When it happens

Trigger: Calling RequirementsParser.parse(req) with a malformed string; `poetry add '<bad string>'` where the spec is neither valid PEP 508 nor a Poetry simple/path/url/git form.

Common situations: Typos like 'requests >=2.31' with stray spaces inside a constraint, missing quotes around shell-passed specs, unparseable VCS URL, or a path that does not exist.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/9750f0fcd7dfb726.json. Report an issue: GitHub.