poetry-build

Build a tarball and a wheel for the project

$ poetry build

$ poetry build [[-f|--format]] wheel

$ poetry build [[-f|--format]] sdist

$ poetry build --clean

$ poetry build [[-o|--output]] [path/to/directory]

poetry build [OPTIONS]

--format=FORMAT
    Specifies the output format of the build. Valid values are sdist (source distribution), wheel (built distribution), or all (both). The default is all.

--no-interaction
    Do not ask any interactive questions during the build process, assuming default answers.

--config=CONFIG
    Specifies an alternative configuration file to use for the build.

-v, --verbose
    Increase the verbosity of messages. Use -v for normal output, -vv for more verbose output, and -vvv for debug output.

-q, --quiet
    Do not output any messages, silencing the command's output.

--ansi
    Force ANSI output, even if the terminal does not appear to support it.

--no-ansi
    Disable ANSI output, preventing color and other ANSI escape codes.

--no-plugins
    Disable the loading of Poetry plugins during the command execution.

--no-cache
    Disable the cache for the build process, forcing a fresh build.

--clean
    Remove the build directory (dist/ by default) before starting the build process.

--allow-prereleases
    Allow the usage of prerelease versions when resolving dependencies for the build.

-h, --help
    Display help information for the build command.

-V, --version
    Display the Poetry application version.

poetry build is a core command within the Poetry dependency manager for Python. Its primary function is to create distributable packages for a Python project. This includes a source distribution (.tar.gz) and a built distribution, commonly known as a wheel file (.whl). These packages are essential for sharing a Python library or application with others, allowing them to install it easily using tools like pip.

The command automatically reads the project's metadata from the pyproject.toml file, including dependencies, version, and entry points, to correctly package the project. It ensures that the built artifacts adhere to Python packaging standards (PEP 517/518) and are ready for publishing to package indexes like PyPI. By default, it builds both formats, but this can be controlled via options.

• Requires a valid pyproject.toml file at the project root with at least the [tool.poetry] section defining project metadata.
• The built artifacts are placed in a dist/ directory by default, created in the project root.
• For projects with specific file inclusion/exclusion needs, ensure these are correctly configured using the include and exclude directives in pyproject.toml.
• If a custom build backend is specified (e.g., using build-system.build-backend in pyproject.toml), that backend will be invoked instead of Poetry's internal builder.

poetry build produces two main types of distribution artifacts:

1. Source Distribution (sdist): A compressed archive (e.g., .tar.gz) containing the source code and metadata needed to build the package from scratch. It is platform-independent.

2. Wheel Distribution (wheel): A pre-built distribution archive (e.g., .whl) that can be installed directly without needing to run any build steps. Wheels are generally faster to install and can be platform-specific or universal.

Both are placed in a dist/ directory by default, ready for installation or publishing.

Poetry's build command adheres to modern Python packaging standards outlined in PEP 517 (A build system independent way of specifying source package builds) and PEP 518 (Specifying build system dependencies for source trees). This adherence ensures broad interoperability with other Python tools and build systems, making packages built with Poetry compatible with the wider Python ecosystem.

Poetry was initially released around late 2017/early 2018 as an alternative to existing Python dependency management and packaging tools. The build command has been a fundamental part of Poetry since its early versions, providing the capability to create standard Python distribution artifacts. Its implementation evolved to align with PEP 517 and PEP 518, ensuring compatibility with modern Python packaging standards and allowing it to serve as a comprehensive build system for Python projects.

poetry publish(1), poetry install(1), pip wheel(1), python -m build(1)