Build system#

The build system is a fundamental tool for packaging Python libraries. It generates distribution files that can be shared with users and developers.


The build system allows maintainers to generate artifacts for their Python libraries. Here, artifacts refers to both wheel and source files:

  • Wheel files have the *.whl file extension.

  • Source files have the *.tar.gz or *.zip extension.

These are the files to upload to PyPI when releasing a new version of a PyAnsys project.


Not all files are included by default in the source distribution. A is required at the root of the project to specify additional files.

The interaction between the maintainer and the build system is performed using a build system tool. This tool provides both a frontend and a backend. The maintainers trigger the frontend, which then calls the backend to read the project directory and generate the artifacts, as Fig. 11 shows.

Maintainers use the build system to create artifacts.

Fig. 11 Maintainers use the build system to create artifacts.#

PEP 517 and PEP 518#

For a long time, the file was the only way of specifying the project structure, metadata, and installation workflow that pip was to follow. However, having to execute a Python file when installing a Python package introduced the following problems:

  • It was not possible to know which dependencies required the file to be properly executed.

  • The default Python package installer, pip, expected setuptools to be the default build system tool, excluding others like flit and poetry.

These problems led to the acceptance of PEP 517 and PEP 518.

PEP 517#

PEP 517 allows Python developers to specify the build backend tool for generating artifacts. The previous Fig. 11 diagram shows the most popular backends:

  • Setuptools , while very popular, lacks the ability to declare build time dependencies and is difficult to extend.

  • Flit is a lightweight build system tool for Python.

  • Poetry focuses on dependency management and environment isolation.

PEP 517 introduced the build-backend key inside the [build-system] table in the pyproject.toml.

PEP 518#

In addition to the file, PEP 518 includes a project file named pyproject.toml. The main goal of this file is to specify build time dependencies. However, some build system tools like flit or poetry are able to specify all project metadata inside the pyproject.toml file and eliminate usage of the file.

To specify the build time requirements, the [build-system] table must be declared in the pyproject.toml file. Within it, the requires key is assigned to a list of strings, which are the build time requirements.

The combination of PEP 517 and PEP 518 leads to the following syntax in a pyproject.toml file:

requires = ["flit"] # Defined by PEP 518
build-backend = "flit_core.api" # Defined by PEP 517

Build backend tools#

This section lists some of the most popular build systems in the Python ecosystem. Although all of them achieve the same goal, there are a few differences regarding their capabilities and the way of specifying project metadata.


Setuptools has been a part of the Python ecosystem for a long time. Unless you require high control over your project’s installation steps, you should use flit or poetry.

If you do not need a dynamic installation process, you can consider using a setup.cfg file. However, the file is still required. The setup.cfg file should have a call to the setup function to act as the entry point of the build backend system.

All of these setuptools metadata fields are valid and must be specified either in the or setup.cfg file.


Flit is a modern and lightweight build system that requires developers to manage virtual environments on their own. Developers must:

  • Create a virtual environment and activate it.

  • Install the package in editable mode.

Flit is the default tool for creating a new pyansys project when using the ansys-templates tool.

The [project] section specifies the project’s metadata and required dependencies. For more information, see flit pyproject.toml guidelines.


Because of its poetry.lock file, Poetry provides strong dependency pinning. When installing a package, poetry creates a virtual environment, thus ensuring an isolated package development environment.

Nevertheless, it is possible to make Poetry ignore the poetry.lock file with:

poetry config virtualenvs.create false --local

Using poetry is popular because it:

  • Supports pinning dependency versions via a poetry.lock file that can be used for testing and CI

  • Allows downstream packages to still consume a loose dependency specification

  • Integrates with dependabot to update the pinned version

The [tool.poetry] section contains metadata and defines project dependencies. For more information, see poetry pyproject.toml documentation.