# libcosmic: a Rust toolkit for building COSMIC desktop applications and applets

> libcosmic is the platform toolkit behind the COSMIC desktop, written in Rust on top of iced and published under the MPL-2.0. It gives you the COSMIC widgets, applet support and desktop integration, but it is tied to one desktop environment and its version numbering does not follow GitHub releases.

**pop-os/libcosmic** — GUI platform toolkit for developing COSMIC applications and applets

- Repository: https://github.com/pop-os/libcosmic
- Website: https://pop-os.github.io/libcosmic/cosmic/
- Stars: 963 · Forks: 214
- Language: Rust
- License: MPL-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/pop-os-libcosmic

## One desktop environment, one toolkit

libcosmic exists to build things for the COSMIC desktop. The repository description calls it a GUI platform toolkit for developing COSMIC applications and applets, and the project puts it more precisely: a platform toolkit based on iced for creating applets and applications for the COSMIC desktop. Two kinds of software are in scope. An application is a normal desktop program. An applet is the smaller thing that lives in the COSMIC panel, and the toolkit has a dedicated feature for it.

The audience is therefore narrow and well defined: Rust developers building software for a Pop!_OS style COSMIC installation, plus the contributors of the COSMIC Store applets that ship in the same ecosystem. If your program has to run on several desktops, this is the wrong level of commitment, and it is worth saying so early, because the dependencies of a COSMIC project do not stay COSMIC specific once you have chosen them.

The crate itself is published as libcosmic but the library target is named cosmic, so an application depends on it under the name cosmic rather than libcosmic. Cargo.toml records version 1.0.0, edition 2024 and a rust-version floor of 1.93, which is a recent toolchain requirement and the first thing to check before you plan a CI matrix around it.

## iced is vendored, and libcosmic is the layer above it

The repository layout explains the architecture. Alongside src, res and examples sit directories for cosmic-config, cosmic-config-derive, cosmic-icons and cosmic-theme, plus an iced directory and a .gitmodules file, which is how the upstream iced codebase is carried inside this repository rather than pulled from crates.io at build time.

So libcosmic is a layer above iced rather than a rewrite of it. The widgets, the application model and the rendering path come from iced, and this repository adds the COSMIC specific parts: the theme, the icon set, the configuration crate and its derive macro, the applet support and the desktop integration hooks. A dependency list in Cargo.toml shows how the optional pieces are wired in, with features such as desktop pulling in cosmic-settings-config and desktop file helpers, and single-instance enabling zbus and ron.

This arrangement has a practical consequence for adopters. Because iced lives inside the repository, the version of iced you get is tied to the checkout of libcosmic, not to your own dependency resolution. You are not free to pick an iced version. For a project that intends to sit on top of libcosmic, that is a constraint rather than a problem, but it means the toolkit's own release rhythm becomes your upgrade rhythm.

## Default features decide your window system and your runtime

The feature list is where the real decisions live, and the defaults are not minimal. Cargo.toml enables winit, tokio, a11y, dbus-config, x11, wayland and multi-window by default, which means a plain build already pulls in both X11 and Wayland support and picks tokio as the async runtime.

Some features are mutually exclusive, and the documentation is explicit about the conflicts. The smol feature uses smol as the preferred async runtime and conflicts with tokio; the tokio feature uses tokio as the preferred async runtime, and if neither is set the default executor defined by iced is used. In the same way the wayland feature gives Wayland compatible client windows and conflicts with winit, while winit gives cross platform and X11 client window support and conflicts with wayland. The two are alternatives in spirit, but the default feature set lists both, and the justfile reflects that by checking the two lanes separately, with one cargo clippy invocation using --features="wayland,tokio,xdg-portal" and another using --features="winit,tokio,xdg-portal".

Rendering is opt in as well. The wgpu feature gives GPU accelerated rendering with WGPU, and by default softbuffer is used for software rendering, so a build without wgpu still draws, just on the CPU. Accessibility support is marked experimental in the documentation, and the xdg-portal feature enables portal dialog integrations, which is how file and other system dialogs reach the desktop.

## Cloning, dependencies and running the bundled examples

The project ships a set of examples in the examples directory, and the documented way to get them is a recursive clone, since the iced submodule has to come along:

```sh
git clone --recurse-submodules https://github.com/pop-os/libcosmic
cd libcosmic
```

If the repository is already cloned, the documented sync is a fetch, a checkout of master and a hard reset onto origin/master:

```sh
git fetch origin
git checkout master
git reset --hard origin/master
```

Before compiling, some dependencies need shared system library headers. On Pop!_OS the project states that the following are all that is necessary for a typical COSMIC project:

```sh
sudo apt install cargo cmake just libexpat1-dev libfontconfig-dev libfreetype-dev libxkbcommon-dev pkgconf
```

That single line tells you a lot about the footprint. Font and text handling pulls in freetype and fontconfig, input handling needs libxkbcommon, and cmake and just are there for the build and the task runner. The examples are then run by their cargo project names, with the command given as just run application. The justfile behind that command runs cargo run --release -p {{name}}, so any of the listed example projects can be launched the same way. The examples cover applet, application, calendar, config, context-menu, cosmic, image-button, menu, multi-window, nav-context, open-dialog, table-view and text-input, which is a decent map of the widget surface.

## Applets and applications go to different submission channels

Distribution is part of the toolkit and it is not uniform. To be identified as a COSMIC application, a project adds a provides entry to its metainfo:

```xml
<provides>
  <id>com.system76.CosmicApplication</id>
</provides>
```

For applets the identifier is different:

```xml
<provides>
  <id>com.system76.CosmicApplet</id>
</provides>
```

Those two identifiers decide where the software can go. Applets must be submitted to the official COSMIC Flatpak repository, which can be added to the system through the COSMIC Store if the operating system has not already installed it. Applications may be submitted to Flathub instead, but desktop specific components such as COSMIC applets are not permitted on Flathub, so anything that is an applet has to take the other route.

There is a second condition that applies before submission: the app or applet must not violate section 5 of the COSMIC trademark policy, which the project points to in the cosmic-epoch repository. Trademark compliance is a packaging requirement in practice, since a rejection at submission time costs a release cycle.

## Version 1.0.0 in Cargo.toml, and no GitHub releases to match it

The repository has no GitHub releases. That is the single most surprising fact about libcosmic for anyone coming from a crates.io library, and it changes how you track versions. Cargo.toml declares version 1.0.0, edition 2024 and rust-version 1.93, but there is no tag list, no changelog on the release page and no release notes to read.

The repository is not archived and the last push was on 2026-10-19, so the code is moving. A consumer who wants a stable point should pin the crates.io version rather than follow the master branch, and should expect to read the repository history rather than release notes when something changes. For a toolkit that the COSMIC ecosystem itself builds on, that is workable but unusual, and it means upgrade planning happens through the dependency version you choose in Cargo.toml.

The licence is the Mozilla Public License 2.0, which is file level copyleft. You can use libcosmic inside a larger application, and modifications to libcosmic files themselves carry the obligation to publish those changes, while the surrounding application files are not pulled in by it. That is a licence reading, not legal advice, and it is the reason many projects pick a different arrangement when a toolkit is embedded deeply.

## Where libcosmic is the wrong choice

Three boundaries are worth stating before you commit. First, portability. libcosmic is for the COSMIC desktop, and its applet support, its panel integration and its config daemon integration are tied to that environment. A cross platform application would be built on iced directly, which is the difference in approach between the two: iced gives you the toolkit and the widgets, while libcosmic adds the COSMIC theme, the icon set, the config and applet conventions and the desktop hooks that only make sense on that desktop.

Second, accessibility. The a11y feature exists and is in the default feature set, but the documentation calls it experimental accessibility support. For a product with a formal accessibility requirement, that label is a reason to test carefully rather than to assume the feature is finished.

Third, the async runtime is a fork in the road. smol and tokio cannot both be enabled, and the default executor defined by iced is used when neither is. If your application already runs on tokio with a large async surface, that is fine, but if it runs on smol you are choosing between that and the tokio default, not having both.

A smaller operational note: generating the documentation the way the project does requires a pinned nightly toolchain. The justfile doc target runs cargo +nightly-2026-04-27 doc with the docsrs cfg set and a wide feature list including tokio, winit, wayland, desktop, single-instance, applet, xdg-portal and multi-window, across the cosmic-client-toolkit, cosmic-protocols and libcosmic packages. The same justfile checks each example with clippy using pedantic warnings enabled, so a patch that only builds may still fail the project's own lint lane.

## Conclusion

Use libcosmic if you are shipping an application or a panel applet for the COSMIC desktop and want the system look, the config daemon integration and the applet packaging rules already solved. Stay on plain iced, or on another toolkit, if your app has to run on other desktops or if you need accessibility support that is still marked experimental here. Verify first that your toolchain meets rust-version 1.93, that the default feature set includes both winit and wayland as you expect, and that the justfile targets you rely on build with the nightly toolchain pinned for doc generation.

## FAQ

### What is libcosmic and what is it used for?

libcosmic is a platform toolkit based on iced for creating applets and applications for the COSMIC desktop. It is written entirely in Rust and provides the COSMIC widgets, themes, icons, configuration handling and applet support.

### What system dependencies does libcosmic need on Pop!_OS?

The project documentation states that on Pop!_OS the following are all that is necessary to compile a typical COSMIC project: cargo, cmake, just, libexpat1-dev, libfontconfig-dev, libfreetype-dev, libxkbcommon-dev and pkgconf.

### How do I run the libcosmic examples?

Clone the repository with git clone --recurse-submodules so the iced submodule is included, then run an example by its cargo project name, for example just run application. The justfile implements that as cargo run --release -p with the project name.

### Where should a COSMIC applet be submitted?

Applets must be submitted to the official COSMIC Flatpak repository, while applications may be submitted to Flathub. Desktop specific components such as COSMIC applets are not permitted on Flathub, and submissions must also respect section 5 of the COSMIC trademark policy.

### Can libcosmic use smol instead of tokio?

Yes, through the smol feature, but smol conflicts with tokio and vice versa. If neither is set, the default executor defined by iced is used, and the tokio feature is the one enabled by default.

## Sources

- [Issues](https://github.com/pop-os/libcosmic/issues)
- [License: MPL-2.0](https://github.com/pop-os/libcosmic/blob/master/LICENSE)
- [pop-os/libcosmic on GitHub](https://github.com/pop-os/libcosmic)
- [Project website](https://pop-os.github.io/libcosmic/cosmic/)
- [README](https://github.com/pop-os/libcosmic/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pop-os-libcosmic