Which Python Build Tool Fits Your Project? A Hands‑On Comparison

Python has long lacked a de‑facto standard project‑management and build tool, resulting in many different project structures and build methods that reflect Python's flexibility.

Unlike Java, which evolved from manual builds to Ant, then Maven (with Gradle, SBT, Ivy, Buildr challenging but not displacing Maven), Python only has package managers such as pip, pipenv, and conda, but no enforced directory layout.

Traditional builds still rely on Makefiles, setup.py, or build.py, and some tools generate project templates.

Below is a brief look at four tools:

CookieCutter

PyScaffold

PyBuilder

Poetry

CookieCutter – a classic Python project layout

$ pip install cookiecutter
$ cookiecutter gh:audreyr/cookiecutter-pypackage   # use the template on GitHub to answer prompts and generate a Python project
... 
project_name [Python Boilerplate]: sample
...

The generated project template looks like this:

$ tree sample
sample
├── AUTHORS.rst
├── CONTRIBUTING.rst
├── HISTORY.rst
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.rst
├── docs
│   ├── Makefile
│   ├── authors.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── history.rst
│   ├── index.rst
│   ├── installation.rst
│   ├── make.bat
│   ├── readme.rst
│   └── usage.rst
├── requirements_dev.txt
├── sample
│   ├── __init__.py
│   ├── cli.py
│   └── sample.py
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── test_sample.py
└── tox.ini

3 directories, 26 files

The core elements are a Makefile, README.rst, docs (with index.rst), requirements.txt, the source package under sample, setup.cfg, setup.py, and a tests directory.

Building the project uses make commands such as:

$ make
clean                remove all build, test, coverage and Python artifacts
clean-build          remove build artifacts
clean-pyc            remove Python file artifacts
clean-test           remove test and coverage artifacts
lint                 check style
test                 run tests quickly with the default Python
test-all             run tests on every Python version with tox
coverage             check code coverage quickly with the default Python
docs                 generate Sphinx HTML documentation, including API docs
servedocs            compile the docs watching for changes
release              package and upload a release
dist                 build source and wheel packages
install              install the package to the active Python site-packages

Required packages (tox, wheel, coverage, sphinx, flake8) are installed via pip, after which commands like make test, make coverage, make docs, and make dist can be run.

PyScaffold – creating a project

$ pip install pyscaffold
$ putup sample

PyScaffold creates a similar layout but places source files in a src directory instead of the project name directory.

$ tree sample
sample
├── AUTHORS.rst
├── CHANGELOG.rst
├── CONTRIBUTING.rst
├── LICENSE.txt
├── README.rst
├── docs
│   ├── Makefile
│   ├── _static
│   ├── authors.rst
│   ├── changelog.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── index.rst
│   ├── license.rst
│   ├── readme.rst
│   └── requirements.txt
├── pyproject.toml
├── setup.cfg
├── setup.py
├── src
│   └── sample
│       ├── __init__.py
│       └── skeleton.py
├── tests
│   ├── conftest.py
│   └── test_skeleton.py
└── tox.ini

Building and testing are performed with tox, which creates isolated virtual environments.

$ tox -av
default environments:
default   -> Invoke pytest to run automated tests

additional environments:
build     -> Build the package in isolation according to PEP517
clean     -> Remove old distribution files and temporary build artifacts
docs      -> Invoke sphinx-build to build the docs
... (other environments omitted for brevity)

Specific tasks are run with commands like tox -e build or tox -e docs.

PyBuilder

Install and start a project:

$ pip install pybuilder
$ mkdir sample && cd sample   # create project directory manually
$ pyb --start-project          # answer prompts to generate files

Resulting structure:

$ tree sample
.
├── build.py
├── docs
├── pyproject.toml
├── setup.py
└── src
    ├── main
    │   ├── python
    │   └── scripts
    └── unittest
        └── python

Tasks are listed with pyb -t sample and defined in build.py. Example snippet:

@init
def set_properties(project):
    project.depends_on('boto3', '>=1.18.52')
    project.build_depends_on('mock')

Poetry

Install and create a new project:

$ pip install poetry
$ poetry new sample

Generated layout:

$ tree sample
sample
├── README.rst
├── pyproject.toml
├── sample
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_sample.py

Poetry manages dependencies in pyproject.toml (similar to Node's package.json). Adding a dependency:

# add boto3 to pyproject.toml and install it
poetry add boto3

Common commands:

poetry build          # build .whl and .tar.gz files
poetry shell          # create and activate a virtual environment based on pyproject.toml
poetry run pytest     # run tests with pytest
poetry run python -m unittest tests/sample_tests.py
poetry export --without-hashes --output requirements.txt

To add a script entry:

# my_module.py
def main():
    print('hello poetry')

# pyproject.toml snippet
[tool.poetry.scripts]
my-script = "sample.my_module:main"

$ poetry run my-script   # prints "hello poetry"

Overall, the complexity of project structures decreases from CookieCutter → PyScaffold → PyBuilder → Poetry, roughly matching the decreasing difficulty of use.