Poetry "Invalid PEP 440 version" - Fix Version Strings in CI

By Daniel Zoghalchali·Latchkey

Poetry validates version strings against PEP 440. A project or dependency version that uses a non-conforming form - a leading v, a date-stamp, or a non-standard separator - is rejected before resolution begins.

What this error means

poetry install/poetry lock/poetry build aborts with Invalid PEP 440 version, naming the offending string. It is deterministic - the same pyproject.toml fails identically until the version is corrected.

Invalid PEP 440 version: 'v1.2.3'
  at ~/.../poetry/core/constraints/version/...
# or
The "version" key in pyproject.toml is not a valid PEP 440 version: 2023.01.01

Common causes

Your project version is not PEP 440

A version like v1.2.3, 1.2.3-rc1 (should be 1.2.3rc1), or 2023.01.01 (leading zeros) violates PEP 440 and Poetry will not accept it.

A dependency exposes a non-conforming version

A constraint or a transitive package’s version string is malformed, surfacing the same parse error during resolution.

How to fix it

Normalize the project version

Use a PEP 440-conforming version: no leading v, pre-release suffixes without a dash, no leading zeros in date segments.

[tool.poetry]
version = "1.2.3"        # not "v1.2.3"
# pre-releases: "1.2.3rc1" (not "1.2.3-rc1")
# date-based: "2023.1.1"  (not "2023.01.01")

Find the offending string

1. Read the exact value Poetry quotes in the error.
2. If it is your project, fix [tool.poetry] version.
3. If it is a dependency, correct the constraint or pin a release with a valid version.

How to prevent it

• Keep your project version PEP 440-conforming.
• Avoid leading v and dashed pre-release suffixes in versions.
• Validate pyproject.toml (poetry check) in CI before publishing.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation