BeeWare is a metapackage, not a library: what installing it really pulls in

A distribution with no modules of its own

The repository describes itself as "A meta-package simplifying the installation of the BeeWare suite of tools", and the project metadata shortens that to "A metapackage to install the full BeeWare suite of tools." Both lines agree on the shape of the thing: the package is a container, not a library. The dependency list in pyproject.toml contains exactly one entry, briefcase, and the top-level repository listing shows no package directory and no module at all, only.github/,.gitignore,.pre-commit-config.yaml, AUTHORS, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, README.md and pyproject.toml. There is nothing to import here. The interesting file is pyproject.toml, and the interesting decision is which dependency it names:

dependencies = [
    "briefcase",
]

Read that as a promise about convenience rather than about capability. A developer who wants a native Python application packaged and distributed is pointed at Briefcase by this package, and everything else the suite contains is not enumerated in this file.

The version number is read from git tags at build time

The version field is not written down anywhere in the metadata. It is declared dynamic and handed to setuptools_scm, which derives a release number from the git history and the tags in the checkout being built. The build requirements pin both tools exactly:

[build-system]
requires = [
    "setuptools==84.0.0",
    "setuptools_scm==10.3.4",
]
build-backend = "setuptools.build_meta"

The consequence for an adopter is concrete rather than theoretical. A published wheel carries a number that somebody tagged, so upgrading means moving to whatever tag upstream last published, not moving to a version listed in a dependency resolver. A local install from a source tree that carries no matching tag gives you whatever fallback the backend decides on. The pyproject.toml even carries a comment explaining that an empty tool configuration is needed to enable SCM versioning, so this is a deliberate arrangement and not an oversight. Two different setuptools_scm versions appear in the file, 10.3.4 in the build requirements and 10.2.1 in the dev dependency group, which is a small inconsistency in a project whose real job is packaging.

Python 3.10 is the floor, and the project still calls itself beta

The metadata names the interpreter range twice, and the two declarations agree. requires-python is set to ">= 3.10", and the classifier list runs from Python 3.10 through 3.14 with a 3-only marker for good measure:

classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: BSD License",
    "Programming Language :: Python :: 3",
]

The Beta classifier is worth pausing on because it is the project's own assessment rather than an outside opinion, and it sits alongside the fact that the only release listed for this repository is v0.3.0 dated 2020-04-18. For a team that plans to pin the suite inside a build pipeline, the practical reading is that this package signals a stable install path for a suite whose release numbering the package itself does not drive. The suite's own tooling, not this metapackage, decides how much of that surface changes between versions.

Where to get it, and what the README asks you to do first

The README does not spell out an install command. It carries PyPI badges for the project, so the route the documentation offers is the package index page linked from those badges, and the package name to look for is the one in the metadata. The links that the project itself publishes are these:

[project.urls]
Homepage = "https://beeware.org"
Funding = "https://beeware.org/contributing/membership/"
Documentation = "https://docs.beeware.org/"
Source = "https://github.com/beeware"

For a first real use, the README points somewhere other than a quickstart. It recommends running the BeeWare Tutorial, hosted at tutorial.beeware.org, as the introduction to the full suite, and it invites readers to talk to the community through the Mastodon account @[email protected] or through Discord at beeware.org/bee/chat. That is the shape of a project where the metapackage is genuinely the small part: the tutorial is where the real workflow lives, and the package simply removes the need to know which pieces to fetch first.

Installing briefcase directly is the leaner alternative

The obvious alternative to installing the metapackage is to depend on briefcase itself and skip the extra layer. The difference in approach is small and worth stating plainly. The metapackage adds a distribution layer whose entire content is the dependency list shown earlier, so it buys you a single install target and a version number derived from git tags. It does not add functionality, and it does not hide the suite's own dependencies, because those are resolved through briefcase regardless of whether briefcase was requested directly or requested through beeware. For a project that only needs Briefcase, adding beeware means two names to track in a lock file instead of one, and it ties your upgrade path to a tag scheme you do not control. The metapackage earns its place when you want the whole suite installed in one step and are happy to take the suite's release cadence along with it.

A push is not a release, and the wheel is expected to be empty

This repository is not archived, and the last push was on 2026-10-05, so work continues on the packaging metadata. That is a different fact from a published release, and the gap between them is wide: the only release listed is v0.3.0 from 2020-04-18. If you are deciding whether the metapackage is current, the push date answers whether the metadata is being edited, while the release tag answers whether anything new was published to PyPI.

The wheel itself is expected to contain nothing. The configuration carries an explicit note that the wheel library is empty, and the wheel content checker is told to ignore the two warnings that emptiness produces:

[tool.check-wheel-contents]
# WOO7: wheel library is empty
# W008: wheel is empty
ignore = "W007,W008"

This is not a defect. It confirms that the artefact you install from PyPI carries metadata and dependency information rather than importable code, which is exactly what a metapackage should look like. It also means you cannot inspect the installed distribution to learn which suite components you ended up with.

Licence, translations and the files a contributor touches

The licence field on the repository says New BSD, and the classifier set names the same family as OSI Approved :: BSD License, with the licence identifier listed as BSD-3-Clause. That is enough to know which terms you are signing up to; it is not a substitute for reading the LICENSE file in the repository root, which is where the authoritative text lives. Note also that a BSD licence on the metapackage does not automatically settle the terms of the suite tools it depends on, so check those separately if licence compatibility matters to your distribution.

For contributors, the file list describes the workflow. Problems are logged on GitHub, code changes arrive as pull requests from a fork, and translations are managed through Weblate rather than by editing strings in the repository. The pre-commit configuration and the pinned pre-commit dependency mean style and spelling checks run before a commit lands, with codespell configured to skip a specific set of directories and to ignore one word from its dictionary. The dev group also fixes setuptools_scm at a specific version for local work. Everything here is packaging hygiene rather than product code, which is the honest summary of this repository.

Editorial conclusion

Adopt beeware when you want a single PyPI entry point for the suite and can tolerate that the package itself contains no code and no install command in its documentation. Do not adopt it expecting a library API to import, a pinned toolchain, or a fresh release, since the last tagged release is v0.3.0 from 2020-04-18 while the last push was on 2026-10-05. Before committing, check the briefcase dependency on the PyPI page for beeware, confirm the pip version tags the suite expects, and read the LICENSE file rather than trusting the BSD label in the classifiers.

Frequently asked questions

Official sources

1. beeware/beeware on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases