Poetry Core

2.3.1 verified Tue May 12 auth: no python install: stale quickstart: stale

Poetry Core is the PEP 517 build backend and core utilities for the Poetry dependency management and packaging tool. The current version is 2.3.1, released on March 27, 2026. Poetry Core is actively maintained with regular updates.

pip install poetry-core

Common errors

error ModuleNotFoundError: No module named 'poetry.core.toml' ↓

cause This error typically occurs when the Poetry installation itself is corrupted or incomplete, leading to its internal components, specifically `poetry.core` modules, being unfindable.

fix

Completely uninstall Poetry and then reinstall it using the official installer script to ensure a clean and correct setup.

error ERROR: Could not build wheels for <package_name> which use PEP 517 and cannot be installed directly ↓

cause This generic error indicates that a package's build process, relying on a PEP 517 backend like `poetry-core`, failed. This is often due to missing system-level build dependencies (e.g., compilers, Python development headers), incompatibility with the current Python version, or issues within the package's build configuration.

fix

Ensure all required system build tools and Python development headers are installed for your operating system. For specific packages, consider installing directly with pip install --no-cache-dir <package_name> or addressing any noted Python version incompatibilities.

error ModuleOrPackageNotFound No file/folder found for package <package_name> ↓

cause This error arises during `poetry build` when the package structure defined or inferred in `pyproject.toml` does not match the actual file system, meaning Poetry cannot locate the source files it needs to package.

fix

Verify that the packages array in your pyproject.toml (under [tool.poetry]) correctly specifies the include path(s) to your source code, or that your project's main module/package name matches the name field if packages is not explicitly defined.

error Poetry could not find a pyproject.toml file in <path> ↓

cause This fundamental error occurs when a `poetry` command is executed from a directory where a `pyproject.toml` file is not present, or in any parent directory, which is necessary for Poetry to recognize the project.

fix

Navigate to the root directory of your Poetry project, which contains the pyproject.toml file. If you are starting a new project, use poetry new <project-name> or poetry init to create one.

Warnings

breaking Dropped support for Python 3.9 in version 2.3.0. ↓

fix Upgrade to Python 3.10 or later.

deprecated The 'project' section in pyproject.toml is now required as per PEP 621. ↓

fix Ensure 'project' section is present in pyproject.toml.

breaking The 'PoetryCore' class cannot be imported directly from the 'poetry.core' module, indicating a breaking API change within the 'poetry' library. ↓

fix Adjust the import statement for 'PoetryCore' according to the updated 'poetry' API documentation or downgrade 'poetry' to a compatible version.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

PoetryCore
```
from poetry.core import PoetryCore
```
Ensure correct import path to avoid ImportError.

Quickstart stale last tested: 2026-04-23

A basic example demonstrating how to import and use PoetryCore to access project metadata.

import os
from poetry.core import PoetryCore

# Initialize PoetryCore with project directory
project_dir = os.path.abspath(os.path.dirname(__file__))
poetry = PoetryCore(project_dir)

# Access project metadata
print(f"Project Name: {poetry.name}")
print(f"Project Version: {poetry.version}")