🧱 Flexbuild

Simple Python build backend for large codebases.

Add to your pyproject.toml:

[build-system]
requires = ["flexbuild"]
build-backend = "flexbuild"

Features

🤸 Flexible source layouts: Place code directly alongside pyproject.toml or in a subfolder like src/module.
🏷️ Virtual namespaces: Define namespace modules like org.department.package without nested folders.
🏗️ Monorepo support: Handle hierarchies of hundreds of packages with minimal boilerplate.
📝 Rich metadata: Entry points, optional dependencies, author and maintainer list, license, and more.
🤝 Ecosystem integration: Integrates seamlessly with packaging tools like uv and pip.
🐣 Hackable: Under 500 lines of easy-to-read Python code with extensive test coverage.

Options

[build-system]
requires = ["flexbuild"]
build-backend = "flexbuild"
module-folder = "."
include = [
    '*.py',
    'pyproject.toml',
    'README.md',
    'README.rst',
]
exclude = [
    'dist',
    'build',
    '__pycache__',
    '.*',
    '*/.*',
    '*.pyc',
]

Monorepos

Flexbuild supports large repositories that contain hundreds of packages with minimal boilerplate. For example, packages can be organized into a folder hierarchy:

repo
  org
    department1
      package1
        pypackage.toml  # project.name = "org.department1.package2"
        __init__.py     # import org.department1.package1
        README.md
        code.py
      package2
        pypackage.toml
        __init__.py
        ...
      package3
    department2
      package1
      package2
      package3

Optionally, create a file repo/pyroot.toml. This enables checks that package namespaces match the folder hierarchy. It also allows specifying [build-system] defaults that nested pyproject.toml files inherit.

Consider using this layout together with uv path dependencies. Unlike uv workspace dependencies, it allows teams to update their version locks independently, so they can move faster and more predictably.

Background

Expand the sections below to to learn details of how Flexbuild solves problems of other Python build backends.

Flexible source layouts

Many Python build backends require a separate module folder inside the package:

package
  pyproject.toml
  src
    module
      __init__.py

Flexbuild looks for the module code at build-system.module-folder = "." from pyproject.toml, which defaults to the package folder but can also be set to a nested folder like src/module.

Virtual namespaces

To define namespace packages that can be imported as import org.department1.package1, many Python build backends require creating nested folders inside the package:

package
  pyproject.toml  # project.name = "org-department1-package1"
  src
    org
      department1
        package1
          __init__.py

Flexbuild allows specifying namespace packages without the nested folders, simply by setting project.name = "org.department1.package1" in the pyproject.toml. This allows simpler folder structures, for example:

package
  pyproject.toml  # project.name = "org.department1.package1"
  __init__.py

Monorepos

To manage a repository with many namespace packages, most Python build backends would require duplicating the same nested folder structure inside of each package:

repo
  org-department1-package1
    pyproject.toml
    README.md
    src
      org
        department1
          package1
            __init__.py
            code.py
  org-department1-package2
    pyproject.toml
    README.md
    src
      org
        department1
          package2
            __init__.py
            code.py
  org-department1-package2
    pyproject.toml
    README.md
    src
      org
        department1
          package3
            __init__.py
            code.py
  org-department2-package1
    ...
  org-department2-package2
    ...
  org-department2-package3
    ...

Through virtual namespaces, Flexbuild allows using a directory structure for namespace packages that can still import each other as import org.department1.package1:

repo
  org-department1-package1
    pyproject.toml
    README.md
    __init__.py
    code.py
  org-department1-package2
    pyproject.toml
    README.md
    __init__.py
    code.py
  org-department1-package2
    pyproject.toml
    README.md
    __init__.py
    code.py
  org-department2-package1
    ...
  org-department2-package2
    ...
  org-department2-package3
    ...

Moreover, it allows placing the packages as leaves of a folder structure. Note that the pyproject.toml files are inside the leaf folders now. This enables organizing packages in a shared folder structure (instead of duplicating the folder structure inside of each package):

repo
  org
    department1
      package1
        pyproject.toml
        README.md
        __init__.py
        code.py
      package2
        pyproject.toml
        README.md
        __init__.py
        code.py
      package3
        pyproject.toml
        README.md
        __init__.py
        code.py
    ...

Questions

Please open a separate GitHub issue for each question.

Metadata

Release files for flexbuild 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flexbuild 0.2.2
File	Size	Uploaded	Provenance	Actions
flexbuild-0.2.2.tar.gz	11.1 kB	Jan 2, 2026	Without provenance	Details for flexbuild-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flexbuild 0.2.2
File	Interpreter	ABI	Platform	Actions Reset
flexbuild-0.2.2-py3-none-any.whl 9.5 kB Jan 2, 2026 Without provenance	Python 3	none	any	Details for flexbuild-0.2.2-py3-none-any.whl

Total release size: 20.6 kB

Release files / flexbuild-0.2.2.tar.gz

Download URL	flexbuild-0.2.2.tar.gz
Size	11.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`07ef24f5f3a49e447d06b282827690937e57b48f1a9efe4401dfdfeba04230e7`
BLAKE2b-256 checksum How to use checksums	`3f33b0c147c07fec34ca5704f9e2120a1a5950efb1899cf03e7fecf57ebbc49c`
Upload date	Jan 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.0`

Release files / flexbuild-0.2.2-py3-none-any.whl

Download URL	flexbuild-0.2.2-py3-none-any.whl
Size	9.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`454cbef58961c87645728df36c67da78321065ea0cdd6b1fe2a3a3cd9833bccb`
BLAKE2b-256 checksum How to use checksums	`d1da03d36ecb21321c6a3dcf46c7a9df418ac82de4227c355314423631db1e9e`
Upload date	Jan 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.0`

Security for flexbuild 0.2.2

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.2 This release

Jan 2, 2026 2 release files No provenance

flexbuild 0.2.2

🧱 Flexbuild

Features

Options

Monorepos

Background

Flexible source layouts

Virtual namespaces

Monorepos

Questions

Project links

Key dates

1 maintainer

Credits

License expression

Requires

Classifiers

Metadata

Project links

Key dates

1 maintainer

Credits

License expression

Requires

Classifiers

Release files for flexbuild 0.2.2

Source distribution (sdist)

Built distribution (wheel)

Release files / flexbuild-0.2.2.tar.gz

Release files / flexbuild-0.2.2-py3-none-any.whl

Security for flexbuild 0.2.2

Provenance

No provenance found

A note on package security

Release history Release notifications | RSS feed

0.2.2 This release

0.2.1

0.2.0

0.1.0