Index

Frequently asked questions

Doesn't my project need a setup.py or setup.cfg file?

No, having a pyproject.toml file is enough.

The setup.py script and the setup.cfg file are specific to the Setuptools build backend. It is not needed for other build systems, such as py-build-cmake, Flit, Poetry etc.

Even when using Setuptools, it's best to avoid setup.py if you can, and to use declarative configuration files like setup.cfg and pyproject.toml instead.
From the Setuptools quickstart guide:

The landscape of Python packaging is shifting and Setuptools has evolved to only provide backend support, no longer being the de-facto packaging tool in the market. Every python package must provide a pyproject.toml and specify the backend (build system) it wants to use. The distribution can then be generated with whatever tool that provides a build sdist-like functionality. While this may appear cumbersome, given the added pieces, it in fact tremendously enhances the portability of your package. The change is driven under PEP 517.

The setup.py file should be used only when custom scripting during the build is necessary. Examples are kept in this document to help people interested in maintaining or contributing to existing packages that use setup.py. Note that you can still keep most of configuration declarative in setup.cfg or pyproject.toml and use setup.py only for the parts not supported in those files (e.g. C extensions).

For more information about setup.py and Python packaging in general, see:

• Why you shouldn't invoke setup.py directly
• Python Packaging User Guide
• PEP 517
• pypa/setuptools: Eventually deprecate setup.cfg with automatic conversion to pyproject.toml

The build fails. How can I find out what's going on?

You can enable py-build-cmake's verbose mode to make it print information about the configuration, the exact subprocesses it invokes, the configure and build environments, and so on.

When using a tool like PyPA build, you can use the -C flag to pass the verbose option:

python -m build . -C verbose

For tools that do not allow options to be passed to the backend directly, you can set the environment variable PY_BUILD_CMAKE_VERBOSE:

PY_BUILD_CMAKE_VERBOSE=1 pip install . -v # Linux/macOS

$Env:PY_BUILD_CMAKE_VERBOSE=1 # Windows
pip install . -v
Remove-Item Env:PY_BUILD_CMAKE_VERBOSE

Also note the -v flag to get pip to print the build output.

When inspecting the output, be aware that output of subprocesses is often much higher up than the final error message or backtrace. For example, if you get an error saying that the invocation of CMake failed, you'll have to scroll up to see the actual CMake output.

How can I perform a clean rebuild?

To fully reconfigure and rebuild a project, simply remove py-build-cmake's cache directory:

rm -r .py-build-cmake_cache

How to upload my package to PyPI?

After building the source and binary distributions using PyPA build, you can use a tool like twine to upload them to PyPI:

• Python Packaging User Guide: Uploading the distribution archives
• https://twine.readthedocs.io/en/latest/

You'll have to upload a single source distribution, and one binary wheel for each combination of Python version and platform you wish to support (see next section).

How to build my package for many Python versions, operating systems, and architectures?

You can use a tool like cibuildwheel to automate the build process for this large matrix of platform/version combinations. Continuous integration providers like GitHub Actions also provide job matrix capabilities. For example, the alpaqa library uses the following matrix to build the package for multiple architectures and Python versions:

strategy:
  matrix:
    pypy: ['', pypy]
    python-version: ['3.8', '3.9', '3.10', '3.11']
    host: [x86_64-centos7-linux-gnu, armv7-neon-linux-gnueabihf, armv6-rpi-linux-gnueabihf, aarch64-rpi3-linux-gnu]
    exclude:
      - pypy: pypy
        python-version: '3.10'
      - pypy: pypy
        python-version: '3.11'
      - pypy: pypy
        host: armv7-neon-linux-gnueabihf
      - pypy: pypy
        host: armv6-rpi-linux-gnueabihf

The same workflow file also contains some steps test the resulting wheels and upload them to to PyPI. It's a good idea to check that the package version matches the Git tag before uploading anything. Also note the use of a secret for the PyPI access token.

To build Universal Wheels for macOS (that work on both Intel- and ARM-based machines), you can set the following environment variables:

export MACOSX_DEPLOYMENT_TARGET='10.14'
export _PYTHON_HOST_PLATFORM='macosx-10.14-universal2'
export ARCHFLAGS='-arch arm64 -arch x86_64'

To build packages for multiple architectures on Linux, I recommend cross-compilation. This ensures that your packge doesn't depend on any libraries (including GLIBC) from the build server. You can use the cross-compilers from https://github.com/tttapa/docker-cross-python, which also include pre-built cross-compiled versions of Python.

This site is open source. Improve this page.