Comparison of Python Project Scaffolding and Build Tools: Cookiecutter, PyScaffold, PyBuilder, and Poetry

Python has long lacked a de‑facto standard for project layout and build tooling, resulting in many divergent structures that reflect the language's emphasis on freedom.

Unlike Java, which converged on Maven (and later Gradle, SBT, etc.) as a near‑standard, Python's ecosystem offers package managers such as pip, pipenv, and conda but provides no consensus on directory layout.

Typical Python projects still rely on traditional Makefile , setup.py , or build.py scripts, and many developers use project‑template generators to impose a structure.

The following four tools are commonly used to create and build Python projects:

Cookiecutter

PyScaffold

PyBuilder

Poetry

Cookiecutter – a classic Python project template

<code>$ pip install cookiecutter
$ cookiecutter gh:audreyr/cookiecutter-pypackage
# answer a series of prompts to generate a new Python project
... (output omitted) ...
project_name [Python Boilerplate]: sample
</code>

The generated sample directory looks like this:

<code>$ 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
</code>

The layout includes a sample package directory, a tests directory for unit tests, a docs folder for Sphinx documentation, and standard build files ( setup.py , setup.cfg , Makefile ).

Typical build commands are driven by the Makefile :

<code>$ 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 into the active Python's site‑packages
</code>

Before using these commands, install the required tools (e.g., tox , wheel , coverage , sphinx , flake8 ) via pip .

PyScaffold – project scaffolding with a src layout

<code>$ pip install pyscaffold
$ putup sample
</code>

PyScaffold creates a similar structure to Cookiecutter but places source code under a src directory instead of directly under the project name:

<code>$ 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
</code>

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

<code>$ 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
  doctests   -> Run doctests via sphinx‑build
  linkcheck  -> Check for broken links in the documentation
  publish    -> Publish the package (defaults to TestPyPI)
  ...
</code>

Specific tasks can be invoked, e.g., tox -e build or tox -e docs .

PyBuilder – Maven‑like build system for Python

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

The generated layout resembles Maven:

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

Build tasks are listed with pyb -t sample and include clean , compile_sources , test , package , publish , etc. Dependencies are declared in build.py :

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

Running pyb creates a virtual environment, installs the declared dependencies, and executes the selected tasks.

Poetry – modern dependency and packaging manager

<code>$ pip install poetry
$ poetry new sample
</code>

Poetry generates a minimal layout:

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

Adding the --src flag places the package under src . Poetry manages dependencies directly in pyproject.toml (a TOML‑based configuration similar to package.json ), e.g.:

<code># add a dependency and install it
poetry add boto3
poetry install
</code>

Key commands include:

<code>poetry build          # build .whl and .tar.gz files
poetry shell          # spawn a virtual environment based on pyproject.toml
poetry run pytest     # run tests inside the virtual env
poetry run python -m unittest tests/sample_tests.py
poetry export --without-hashes --output requirements.txt
</code>

Poetry does not handle documentation, linting, or coverage out of the box; those tools must be invoked via poetry run (e.g., poetry run sphinx-build , poetry run coverage , poetry run flake8 ).

Overall, the complexity of the generated project structure decreases from Cookiecutter → PyScaffold → PyBuilder → Poetry, while the learning curve follows the same order.