BitBake is the task engine that OpenEmbedded and Yocto run their builds on

A task engine, not a build system

BitBake is described as a generic task execution engine that allows shell and Python tasks to be run efficiently and in parallel while working within complex inter-task dependency constraints.

That definition is the whole product, and it is worth pausing on the word generic. BitBake does not define what a recipe is, what a layer is, how a cross-toolchain is laid out or what a distribution looks like. It knows how to work out what needs to be built, in what order, and how to run the steps.

The consequences of that separation are visible throughout the ecosystem. OpenEmbedded takes this core and builds embedded Linux software stacks using a task-oriented approach. Yocto builds on OpenEmbedded. Neither of them is BitBake, and both of them could in principle be rewritten on a different engine without changing what a user sees.

The practical value of the separation is that the hard part, which is dependency resolution and parallel execution across thousands of interdependent steps, is solved once and reused by everything built on top. The cost is that learning BitBake on its own tells you about the engine and not about the thing you actually want to build, which is why the documentation lives under the Yocto Project site rather than on a standalone site.

The plain documentation is in the doc/ directory of the repository, and the integrated HTML version is at docs.yoctoproject.org. BitBake requires Python 3.9 or newer, and the package metadata in pyproject.toml gives the current version as 2.20.0 with requires-python of >=3.9.

The repository layout, and what each directory is for

The top level of the repository is the clearest description of the engine's parts.

There is lib/ for the library code, classes/ for the task and provider classes, conf/ for the configuration, contrib/ for contributed utilities, bin/ for the command line entry points, and doc/ for the documentation. There is default-registry/ for the registry data, setup-schema/ for the schema definitions, packaging-pypi/ for the packaging work, and vendor/ with vendor.txt for the vendored dependencies.

The tests live in lib/bb/tests/, which the README describes as a testsuite aimed at trying to prevent regressions, run with bitbake-selftest.

Two details in that list are more than they look. The vendor/ and vendor.txt arrangement is a real design decision, and the pyproject.toml shows how it works: the vendoring destination is lib/bb/_vendor, the namespace is bb._vendor, the patches directory is vendor/patches, and the requirements come from vendor.txt. There is even a licence fallback URL for one dependency, ply, which points at a specific file on a branch rather than a tag.

That last detail is the kind of thing that matters when you audit a build system. The vendored ply is pinned to a branch head rather than a fixed release, so the licence record for it is kept in the repository at vendor/licenses/ply/LICENSE with a fallback URL recorded in pyproject.toml.

The licence files at the root reflect that BitBake is dual licensed: LICENSE.MIT and LICENSE.GPL-2.0-only sit alongside a custom LICENSE, which is why the project licence is recorded as one GitHub cannot classify.

Running the test suite, and the environment it assumes

The Testing section is short and has one piece of advice that matters: testing with the testsuite is recommended before submitting patches, particularly to the fetcher and datastore.

The reason those two are called out is given. The fetcher is well covered since it has so many corner cases, and the datastore has many tests too. The fetcher is where a build goes to fetch source from a hundred different kinds of remote, and the datastore is where BitBake keeps its parsed metadata, so a regression in either shows up as a build that fails for reasons far from the change that caused it.

To run the tests, zstd and git must be installed.

The assumption is that the testsuite is run from an initialized OpenEmbedded build environment, which means source oe-init-build-env is used. If that is not the case, the testsuite is run directly from the checkout.

    export PATH=$(pwd)/bin:$PATH
    bin/bitbake-selftest

The testsuite can alternatively be executed using pytest, obtained for example from PyPI, in which case the PATH is configured automatically.

    pytest

That last option is worth knowing, because it means the test suite is runnable without an OpenEmbedded environment if you have the Python dependencies, which lowers the barrier for a contributor who is not building embedded images.

The README also says that new test cases are appreciated and may be required for more obscure issues. That is a signal about how the project handles bug reports: a fix for an obscure fetcher corner case without a test is likely to come back asking for one.

Contributing, and where the real repository is

The contributing guidance has a detail that trips up newcomers, and it is at the top of the README.

The official bitbake Git is at git.openembedded.org/bitbake/, and the instruction is not to open issues or file pull requests here. This GitHub repository is a mirror.

The contributor guide is at docs.yoctoproject.org/contributor-guide/, with the full details on how to submit changes. As a quick guide, patches should be sent to [email protected], and the git command to do that is:

    git send-email -M -1 --to [email protected]

And if the patch is related to the BitBake manual, you copy the Yocto Project documentation mailing list as well.

    git send-email -M -1 --to [email protected] --cc [email protected]

So contributions go by email to a mailing list, not by pull request, and the mailing list is at lists.openembedded.org/g/bitbake-devel. That is a mature open source process rather than a modern repository workflow, and it means the review conversation happens on a list archive rather than in a pull request thread.

The last push to the mirror was on 2026-10-19, the default branch is master, and the repository has no GitHub releases. The AUTHORS file and the ChangeLog at the root record the history of the project.

Where BitBake is the wrong choice

Three cases argue against it.

The first is if you want to build software. BitBake will not tell you how to write a recipe, how to structure a layer, how to set up a cross-compilation toolchain or what a distro configuration looks like. If your goal is to produce an embedded Linux image, you want OpenEmbedded or Yocto, and BitBake is a component inside them rather than the thing you configure.

The second is if you want a general build tool. The engine is capable, but it is tuned for the case OpenEmbedded needs, which is fetching and building large dependency graphs of source packages with heavy cross-compilation and per-machine configuration. Using it standalone means building that configuration layer yourself.

The third is if you want to contribute through a pull request. The README says not to open issues or file pull requests on this repository, so your workflow has to be email to a mailing list.

The alternative in the same direction is to build on the layer system rather than the engine, which is what most contributors actually do. OpenEmbedded and Yocto give you recipes, classes and a toolchain configuration layer on top of the same engine, and the difference in approach is that working at the layer level means you write metadata rather than Python, and your changes are far more likely to be accepted upstream because they are expressed in the terms the project understands. The engine itself is where you go when a fetcher or datastore bug is the actual problem, and that is a narrower and better defined kind of contribution.

Editorial conclusion

BitBake fits a developer working inside an OpenEmbedded or Yocto build who needs to understand how task dependencies are resolved, how the datastore behaves and how the fetcher handles the awkward cases, because the test suite covers those areas deliberately. It does not fit a team that wants a standalone build tool, since BitBake defines no layer structure, no recipe format and no toolchain of its own. Read the documentation under doc/ or at docs.yoctoproject.org, run `bitbake-selftest` from an initialised build environment before submitting patches, and note that the canonical source is the git at git.openembedded.org rather than this GitHub mirror.

Frequently asked questions

Official sources

1. Issues
2. openembedded/bitbake on GitHub
3. Project website
4. README