poetry build: Build Artifacts Command Reference

Build distributable artifacts straight from your Poetry project.

poetry build creates a source distribution and a wheel in dist/ using the metadata in pyproject.toml. It is the build step before publishing a Poetry-managed package.

Common flags / usage

• poetry build -- build both sdist and wheel into dist/
• --format wheel -- build only the wheel
• --format sdist -- build only the source distribution

Example

- run: pipx install poetry
- run: poetry build
- uses: actions/upload-artifact@v4
  with:
    name: dist
    path: dist/*

In CI

Building fails if required project fields (name, version) are missing or malformed in pyproject.toml. Upload dist/ as an artifact so a separate poetry publish or twine job can ship it.

Key takeaways

• poetry build emits an sdist and wheel into dist/.
• --format restricts output to just the wheel or sdist.
• Complete project metadata is required for the build to succeed.

Related guides