KivyMD 2.0.0: Material Design widgets for Kivy, and who should not use it

What KivyMD 2.0.0 adds to a Kivy application

Kivy gives you a cross-platform, touch-enabled application framework in Python. It does not give you Material Design. KivyMD fills that gap with a widget collection that the README describes as Material Design compliant, and it states the goal plainly: approximate Google's Material Design spec as closely as possible without sacrificing ease of use.

The audience is narrow and specific. You are writing a Python application with Kivy, you want AppBar, BottomAppBar, BottomSheet, Card, Chip, DatePicker, Dialog, DropdownItem, ExpansionPanel, Hero, ImageList, LoadingIndicator and similar components rather than raw canvas instructions, and you intend to ship to more than one platform. The repository's topics list android, ios, linux, macos, windows, so a single codebase across those targets is the stated intent.

The fork matters. The README says this library is a fork of the KivyMD project hosted on GitLab, and that the maintainers brought it to a new level. That is a governance fact, not a technical one, but it decides where you file issues and which documentation you read. If you find a tutorial dated before the fork, check whether the API it uses still exists in 2.0.0.

How the widget layer sits on top of Kivy

KivyMD does not replace Kivy's event loop or its graphics backend. It ships as a Python package, kivymd/, alongside docs/, examples/ and a pyproject.toml at the repository root. Your application still builds a Kivy App, still loads a .kv file if you use one, and still runs on Kivy's window and input system. KivyMD supplies widget classes that render Material-styled components inside that system.

The dependency list in the README tells you what the widgets actually lean on. Kivy >= 2.3.0 is the base. Pillow handles images. PyCairo is a separate install with its own instructions, and the README links out to them rather than describing the build. MaterialColor >= 3.0.3 and MaterialShapes come from the same author, and the dynamic color examples in examples/dynamic_color_image.py and examples/dynamic_color_schemes.py suggest those packages drive the theming path. asynckivy appears in the dependency list, which points at asynchronous work inside the widget layer.

That chain is the real architecture story. KivyMD is thinner than it looks: a large part of what you get is a curated set of widgets plus theming, with the heavy lifting delegated to Kivy for rendering and to PyCairo, MaterialColor and MaterialShapes for color and shape. When something renders incorrectly, the fault may sit in any of those, and the README does not map which widget depends on which package.

Installing KivyMD and running a first widget

The README gives one command for the current release. It pins the version explicitly, which is the safer habit given the fork history and the absence of release notes in the repository metadata.

pip install kivymd==2.0.0

After that, the README lists the dependencies you need present: Kivy >= 2.3.0, Python 3.7 or newer, Pillow, PyCairo, MaterialColor >= 3.0.3, MaterialShapes and asynckivy. PyCairo is the one to expect trouble from, because the README points to its own installation page instead of covering it here. Install it before you file a bug against KivyMD.

If you want the development branch rather than the release, the README gives a zip archive URL instead of a version pin. The tip is to replace master.zip with a commit hash, for example 51b8ef0.zip, so the install is reproducible.

pip install https://github.com/kivymd/KivyMD/archive/master.zip

For a source checkout, the README clones shallow and installs from the working directory. The note about --depth 1 is worth reading: full commit history is about 1.14 GiB, so the shallow clone is not a minor optimisation.

git clone https://github.com/kivymd/KivyMD.git --depth 1
cd KivyMD
pip install .

For a first real use, the repository ships runnable files under examples/. examples/appbar.py, examples/card.py and examples/datepicker.py are individual widget demos, and examples/common_app.py appears to be the shared scaffold several of them import. Run one from a source checkout and you get a Kivy window showing that widget. The README also points to a Kitchen sink demo application and a wiki with widget examples; the wiki is where the README sends you for usage patterns, not the README itself.

Packaging for Android and iOS is where the cost lands

The README devotes more space to Buildozer and kivy-ios than to writing widgets, which is a fair signal about where effort goes. For Android, the requirements block in buildozer.spec is long and explicit, and it names packages you would not otherwise expect to list by hand.

requirements = python3,
    kivy,
    https://github.com/kivymd/KivyMD/archive/master.zip,
    materialyoucolor==3.0.3,
    materialshapes,
    pycairo,
    pillow,
    exceptiongroup,
    asyncgui,
    asynckivy,
    android

Note that this block pulls KivyMD from the master zip, not from PyPI, even though the prose above it says the opposite. If you want the release, change that line to kivymd. Also note the README's warning: run buildozer android clean or delete the .buildozer directory after a version change, because Buildozer does not update packages it has already downloaded. That is a real failure mode, and it produces stale builds that look like KivyMD bugs.

On Linux the README says to use Buildozer directly or through its Docker image. On Windows 10 it says install Ubuntu WSL and follow the Linux steps. There is no native Windows build path documented. For iOS, the kivy-ios route is two commands, and the second one skips dependency resolution.

toolchain build python3 kivy pillow
toolchain pip install --no-deps kivymd

The --no-deps flag means you are responsible for whatever kivymd would otherwise pull in. The README does not say which packages that leaves you to install on iOS.

Where KivyMD is the wrong choice

The clearest limitation is the build environment. If your team develops on Windows without WSL, the README offers no Android path. If you cannot run Linux, you are building through Docker or not at all.

The second is the dependency surface. PyCairo, MaterialColor, MaterialShapes and asynckivy all sit between your code and a working window. The README documents none of their failure modes, and it does not say what happens when MaterialColor resolves to a version below 3.0.3. A pinned install in your own requirements file is the only defence the documentation supports.

The third is documentation depth. The README is an install guide plus links. Widget behaviour lives in the readthedocs site and the wiki, and the repository's own examples are the only executable specification shipped with the source. If you need a documented API contract before you write code, this is not that kind of project.

Finally, consider whether you need KivyMD at all. If your application is a handful of buttons and labels, plain Kivy is enough and you avoid four dependencies. KivyMD earns its place when you would otherwise reimplement Material components yourself.

KivyMD compared with Flutter and React Native

The comparison people search for is KivyMD against Flutter and React Native, and the difference is the language boundary rather than the widget set. Flutter and React Native are the mainstream route to Material-styled mobile applications, and both have far larger ecosystems. KivyMD's case rests on Python.

If your application logic, your data processing or your team's existing code is Python, KivyMD keeps one language across the whole stack. With Flutter you would rewrite that logic in Dart, and with React Native in JavaScript or TypeScript. That is the actual trade: KivyMD gives you Python and a smaller widget catalogue, while the alternatives give you a larger catalogue and a second language.

Against Kivy itself, the distinction is simpler. Kivy is the framework, KivyMD is the widget collection on top of it. KivyMD cannot be used without Kivy, and it does not change how Kivy schedules frames or handles input. Choosing between them is choosing whether you want Material components pre-built.

One note on maturity signals: the README shows coverage, build, release, test and documentation badges, and the repository has a .pre-commit-config.yaml, a .readthedocs.yml and a docs/ directory. Those tell you the project runs tests and publishes documentation. They do not tell you how stable any individual widget is, and the README does not claim a stability level for 2.0.0.

Licence, maintenance and upgrade cost

KivyMD is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive: you can use it in closed-source applications, and the obligation is essentially attribution and inclusion of the licence text. That is a description of the licence, not legal advice; your own counsel decides how it applies to your distribution, particularly when you bundle it into a mobile binary.

The dependency licences are a separate question the README does not address. Kivy, Pillow, PyCairo, MaterialColor, MaterialShapes and asynckivy each carry their own terms, and you are distributing all of them in an Android or iOS build. Check them individually.

On maintenance: the repository is not archived, and the last push was on 2026-09-24. The README documents 2.0.0 as the current release, and no release notes were published alongside it, so the changelog link in the README is the place to look for what changed between versions.

Upgrade cost is dominated by the packaging step rather than the API. The README's own instruction to run buildozer android clean or remove .buildozer before rebuilding is the recurring tax: any version bump means a clean rebuild, and the README says Buildozer will not update already downloaded packages. Budget for that on every upgrade, and pin your version in buildozer.spec rather than tracking master.

Editorial conclusion

Adopt KivyMD if you already write Kivy applications in Python and want Material components without hand-building them, and if you can accept the fork from the original KivyMD project. Do not adopt it if you want a web stack, or if your team cannot build and test on Android and iOS from a Linux or WSL environment. Before committing, verify that Kivy >= 2.3.0, PyCairo and MaterialColor >= 3.0.3 install cleanly on your target platform, and confirm which branch you are pinning.

Frequently asked questions

Official sources

1. Issues
2. kivymd/KivyMD on GitHub
3. License: MIT
4. Project website
5. README