Jump to content

KDE Linux: Difference between revisions

From KDE Community Wiki
← Older edit
mention nvidia cards
Ngraham (talk | contribs)
KDEDevelopers, Administrators, trusted
2,324 edits
Add a stub for installing fonts
 
(214 intermediate revisions by 13 users not shown)
Line 1: Line 1:
"KDE Linux" (codenamed "Project Banana") is a work-in-progress name of a KDE-owned general-purpose Linux® distribution proposed at Akademy 2024. Not to be confused with [https://neon.kde.org KDE neon].
[[File:Kde-linux-logo.png|frameless|right|200px]]


{{ Warning | This page serves as a design document, thus information presented here should be considered a snapshot of the ongoing discussion, not final decisions. }}
"KDE Linux" (codenamed "Project Banana") is a KDE-owned general-purpose Linux®-based operating system revealed at Akademy 2024 ([https://conf.kde.org/event/6/contributions/202/attachments/135/171/The%20Operating%20System.pdf slides], [http://www.youtube.com/live/gTxRaBEUe-I?t=25936 recording]), being developed at https://invent.kde.org/kde-linux. The goal of KDE Linux is to create a bulletproof OS showcasing the best of KDE that we can proudly recommend to users and OEMs, with a coherent "here's how you get it" story.


This page has lots to talk about, please consult the table of contents on the left :)
KDE Linux is an "immutable base" operating system that does not include a traditional package manager. Apps can be installed from Flatpak, Snap, or AppImages. There are [[KDE_Linux/Install_software_not_available_in_Discover|various other options]] for getting software from other sources. System updates involve replacing the OS image with an entirely new one.


== Goals ==
For more information, see [[KDE_Linux/Background_information|Background information]].


TL;DR: Create a bulletproof OS showcasing the best of KDE that we can proudly recommend to users and OEMs, with a coherent "here's how you get it" story.


Goals in detail:
== Current state ==
* Be "The KDE operating system"
KDE Linux has completed its [https://invent.kde.org/groups/kde-linux/-/milestones/3 Alpha release], which includes the Testing Edition. Work now focuses on the [https://invent.kde.org/groups/kde-linux/-/milestones/2 Beta release].
* User-friendly; high-quality UX
* Doesn't break, or at least easy to recover
* Keeping security in mind
* No packaging knowledge needed to develop for it
* Focus on modern technologies
* Attractive for our hardware partners
* Any edition can be used as the main system by our developers for internal dogfooding purposes
* Support switching between editions/release schedules at any time
* Exercise codepaths for containerized apps and immutable base systems, to improve KDE software deployed using these technologies in other environments


=== Non-goals ===
The Testing Edition provides built-from-git-master versions of Plasma, KWin, and KDE apps. Getting apps from Flathub works. Developing KDE and 3rd-party software works. System Updating using Discover and the command-line works. System rollbacks work. General "daily driving" should be usable for adventurous people.
Does not have to support the runtime installation of kernel modules. This will prevent the out-of-the-box installation of, for example:
* Proprietary NVIDIA kernel driver (for graphics cards older than Nvidia RTX 4xxx). NVIDIA GPUs must either be new enough to use the open-source kernel modules that can be distributed in-tree, or else use Nouveau
* VirtualBox (requires out-of-tree modules; QEMU/KVM probably do a better job anyway)
* Vendor-specific VPNs that require custom out-of-tree kernel modules that cannot be redistributed with the kernel due to license incompatibility


Does not have to support the use case of developing low-level system components like the kernel, drivers, systemd, etc., as this can be troublesome with an immutable base OS.
Some things [https://invent.kde.org/kde-linux/kde-linux/-/issues/ don't work well yet]. Notable examples include:


== Target audience and use cases ==
* Secure Boot [https://invent.kde.org/kde-linux/kde-linux/-/issues/3 isn't yet supported].
* Manual partitioning [https://invent.kde.org/kde-linux/kde-linux/-/issues/296 doesn't work] [https://invent.kde.org/kde-linux/kde-linux/-/issues/299 right now].
* Trash [https://bugs.kde.org/show_bug.cgi?id=513350 isn't available for locations outside your home folder]; you have to immediately delete things in those locations.
* Java software [https://invent.kde.org/kde-linux/kde-linux/-/issues/447 doesn't run without manually installing Java somehow].
* The [https://invent.kde.org/kde-linux/kde-linux/-/issues/79 QA & testing infrastructure] needs more thoroughness and automation. Until then, expect some bad builds from time to time that you'll need to roll back.
* NVIDIA GPUs older than the GTX 1630 [https://invent.kde.org/kde-linux/kde-linux/-/issues/269 require manual work to use].
* Disk monitoring in System Monitor + widgets [https://invent.kde.org/kde-linux/kde-linux/-/issues/208 doesn't work].
* KDE apps in Flatpaks [https://invent.kde.org/kde-linux/kde-linux/-/issues/71 have rough edges].
* System updates are huge because we ship a whole new OS image, and [https://github.com/systemd/systemd/issues/28227 delta updates haven't been implemented in Systemd yet]. A bespoke delta updating system is in progress.
* Using Discover to update the system and install large Flatpaks [https://invent.kde.org/kde-linux/kde-linux/-/issues/147 has rough edges].
* The developer story for working on frameworks and libraries used in Flatpak apps [https://invent.kde.org/kde-linux/kde-linux/-/issues/232 is somewhere between "painful" and "non-existent"].
* Thus far, only a handful of KDE contributors have been using and testing KDE Linux, so there may be other significant issues.


It should have multiple editions using different release schedules, suitable for different kinds of users. Ideas:
* '''Testing edition''': built from git master and released daily. Like KDE neon Testing. ''For QA people, Plasma developers, and Patrick Silva.
* '''Enthusiast edition''': ships released software, and releases to users on upstream KDE's schedule, like KDE neon User. Additionally, when there are any beta releases, ships the beta. ''For KDE enthusiasts, power users, and influencers.''
* '''Stable edition''': ships only released software on a delayed schedule, based on TBD quality metrics. ''For everyone else.
''
== Architecture ==


Original architecture ideas for the project included the following:
== Getting it ==
Download the latest .raw image from https://files.kde.org/kde-linux/?C=M;O=D.


* Reproducible builds, must-pass CI, automated UI testing
Verify that it arrived in one piece:
* Base OS is Arch-based. OS updates are some degree of rolling; snapshot based releases with relatively recent libraries
# Go to https://files.kde.org/kde-linux/?C=M;O=D and click "Details" for the .raw file you downloaded. Copy the long string of nonsense characters next to "SHA256". This is the SHA256 checksum of the .raw file.
* Systemd-boot as the bootloader with nice boot theming
# Once the .raw file has finished downloading, right-click on it, choose "Properties", and then click "Checksums" tab. Ensure the text field at the top is green. If it is, the file on your computer is the same one that you downloaded.
* Btrfs as the filesystem
* Encryption of all mutable data (e.g. user homedir, and cache locations on /)
* Included recovery partition
* Read-only base system, like SteamOS 3, Fedora Kinoite, and openSUSE Kalpa
* Atomic image-based A/B updates with rollback functionality
* Instead of legacy packages we target modern deployment systems such as flatpak and systemd-sysext
* Apps are from Flatpak (and maybe also Snap if it's not too hard and the UX is okay)
* Wayland by default
* Automatic user data backup system using Btrfs snapshots, with a nice GUI around it like Apple's Time Machine
* DConf-like configuration management UI suitable for enterprise and managed environments leveraging KConfigXT for everything
* Simple input method configuration for CJK and more
* "Troubleshooting hub" app


TODO: hardware support, software separation, security model, deployment, OEM mode; proposed solution, alternatives, trade-offs for each section
To install on physical hardware, see https://kde.org/linux/install.


=== updates ===
To install in a virtual machine, see [[KDE_Linux/installing_on_a_virtual_machine|Installing in a virtual machine]].


=== systemd-sysext ===


systemd-sysext allows us to overlay developer content on top of /usr without impacting the base system.
== How to ==
Life on a cutting-edge immutable OS can be unfamiliar! Here's how to do various things you might be wondering about:


=== Setup ===
=== Hardware support ===
* [[KDE_Linux/Enable_hardware_acceleration_for_Firefox_on_NVIDIA_GPUs|Enable hardware acceleration for Firefox on NVIDIA GPUs]]
* [[KDE_Linux/Use_a_pre-Turing_(older_than_GTX_1630)_NVIDIA_GPU|Use a pre-Turing (older than GTX 1630) NVIDIA GPU]]


{{Input|1=<nowiki>
=== Basic use ===
# create directories
* [[KDE_Linux/Install_apps_and_games|Install apps and games]]
mkdir -p ~/kde/usr/lib/extension-release.d/
* [[KDE_Linux/Install_fonts|Install fonts]]
# create an extension-release file
* [[KDE_Linux/Update_the_system|Keep the system up to date]]
cp /usr/lib/os-release ~/kde/usr/lib/extension-release.d/extension-release.kde
* [[KDE_Linux/Backup|Back up data]]
# make the ID ignored so updates don't break the extension
* [[KDE_Linux/Auto-mount_internal_disks|Auto-mount internal disks]]
sed -i s%^ID=.*%ID=_any%g ~/kde/usr/lib/extension-release.d/extension-release.kde
# owned by root so it can't be removed
sudo chown root:root ~/kde/usr/lib/extension-release.d/extension-release.kde
# enable the extension
sudo mkdir /var/lib/extensions/
sudo ln -s $HOME/kde /var/lib/extensions/kde
sudo systemd-sysext merge
sudo systemd-sysext
</nowiki>}}


=== Use ===
=== Advanced use ===
* [[KDE_Linux/Multi-GPU|Force software to run on the dedicated GPU with a multi-GPU setup]]
* [[KDE_Linux/Install_software_not_available_in_Discover|Install Linux software not available in Discover]]
* [[KDE_Linux/Install_windows_software|Install software only available on Windows]]
* [[KDE_Linux/Run_Java_software|Run Java software]]
* [[KDE_Linux/Use_KeepassXC_with_Web_Browsers|Use KeepassXC with Web Browsers]]
* [[KDE_Linux/Add_or_override_content_in_/usr|Add or override content in /usr]]
* [[KDE_Linux/Create_and_use_virtual_machines|Create and use virtual machines]]


Use DESTDIR=~/kde to install stuff and then restart systemd-sysext. Beware that when changing polkit/dbus stuff you also want to restart those services as they don't necessarily pick up changes.
=== Software development ===
* [[KDE_Linux/Develop_KDE_software|Develop KDE software]]
* [[KDE_Linux/Develop_or_run_Python_scripts|Develop or run Python scripts]]
* [[KDE_Linux/Kernel_Development|Develop or debug the kernel]]
* [[KDE_Linux/Develop_other_non-KDE_software|Develop other non-KDE software]]
* [[KDE_Linux/Develop_KDE_Linux_locally|Develop KDE Linux locally]]


{{Input|1=<nowiki>
=== Troubleshooting and debugging ===
DESTDIR=~/kde ninja install && sudo systemctl restart systemd-sysext.service
* [[KDE_Linux/Recover_from_boot_failures|Recover from a failure to start up properly]]
</nowiki>}}
* [[KDE_Linux/Debug_crashes_in_Flatpak_apps|Debug crashes in Flatpak apps]]
* [[KDE_Linux/Migrate_older_installations|Migrate older installations]]


== Prototype ==


The code is currently located [https://invent.kde.org/sitter/kde-linux here]. Note that it is '''not representative of the final product''' and exists as an experimental playground for now.
== Get involved ==
The KDE Linux team is super excited to receive new contributors! The OS is quite easy to hack on, and the developers hang out in the [https://matrix.to/#/%23kde-linux:kde.org #kde-linux:kde.org Matrix room].


=== Installation ===
* To propose changes, submit a Merge Request in [https://invent.kde.org/kde-linux/ one of the relevant git repositories].
==== GUI ====
* To report issues in the KDE Linux operating system itself (i.e. OS design, integration, system services, etc), use [https://invent.kde.org/kde-linux/kde-linux/-/issues/new invent.kde.org], and ignore the scary red banner at the top of the page.
Use [https://apps.kde.org/isoimagewriter/ ISO Image Writer]
* To report issues in KDE Plasma or any KDE apps, use [https://bugs.kde.org/ bugs.kde.org].
* To get help with something that's not necessarily a bug, use [https://discuss.kde.org/ discuss.kde.org], and tag your post with "kde-linux".


==== Terminal ====
* [https://files.kde.org/kde-linux/ Download] the latest <code>.raw</code> file
* Attach a USB drive
* Use <code>lsblk</code> to find the right <code>/dev/node</code>. e.g. <code>/dev/sda</code>
* <code>sudo dd if=kdeos.raw of=/dev/sda bs=4M</code>
* <code>sudo sync</code>
* Reboot into the USB stick
* no password on SDDM


==== Install ====
== Further Reading ==
Run "Install System" (Calamares) from the "Welcome Center" app by single clicking on the icon or from the KDE Plasma desktop by double clicking on the app or from the KDE Plasma start menu (Application Launcher) > System > Install System.
* [[KDE_Linux/Obstsalat]]
* [[KDE_Linux/RootFSv2]]
* [[KDE_Linux/Verity]]
* [[KDE_Linux/Delta]]
* [[KDE_Linux/Banana_Split]]
* [[KDE_Linux/Storage]]


In the installer wizard, at the page 4 "Partitions", from the "Select storage device:" combo box, select the storage device which does not contain the currently running operating system. E.g. if installing inside a virt-manager VM select "/dev/vdb" and then select "Erase disk".


==== Updates ====
== External Resources ==
 
* Background information from Lennart Poettering about OS design: https://0pointer.net/blog/fitting-everything-together.html + https://0pointer.net/blog/testing-my-system-code-in-usr-without-modifying-usr.html
Until discover gets support the following needs running
* Presentation by Harald Sitter at Akademy 2024 ([https://conf.kde.org/event/6/contributions/202/attachments/135/171/The%20Operating%20System.pdf slides], [http://www.youtube.com/live/gTxRaBEUe-I?t=25936 recording]).
 
* Presentation by Harald Sitter at Akademy 2025 ([https://conf.kde.org/event/9/contributions/265/attachments/171/220/growth.pdf slides], [https://www.youtube.com/watch?v=PA03J1CAYoA recording]).
{{Input|1=<nowiki>
* [https://pointieststick.com/2025/09/06/announcing-the-alpha-release-of-kde-linux/ Alpha release announcement]
git clone https://invent.kde.org/sitter/kde-linux
cd kde-linux
sudo ./update.sh update
</nowiki>}}
 
=== VM ===
 
==== virt-manager ====
 
* File > New Virtual Machine > Import existing disk image
* [Forward]
* In "Provide the existing storage path:" > Browse, select from disk the raw file that you have downloaded.
* In "Choose the operating system you are installing:" write "Arch Linux".
* [Forward]
* In "Choose Memory and CPU settings:" set resources.
* [Forward]
* Enable the check box "Customize configuration before install".
* [Finish]
* Config window opens
* Make sure at the bottom it says Firmware: UEFI
* On the bottom left, click the button "Add Hardware".
* Add a storage of some reasonable size. E.g. "Create a disk image for the virtual machine" 200 GB. Press the "Finish" button.
* Press the "Begin Installation" button. The VM will start.
 
If the VM fails to boot and shows the error "No bootable option or device found.". Press Enter, this will start the UEFI user interface. Disable Secure Boot from the UEFI user interface. Device Manager > Secure Boot Configuration > Attempt Secure Boot disable the check box by pressing the Space keyboard key. F10 to save, 'y' keyboard key. Press the "Escape" keyboard key twice, select "Reset".
 
Install the operating system to the second virtual disk. After installing the OS is done, shut down the VM.
 
"VirtIO Disk 1" contains the raw file that you have downloaded.
 
Edit the VM configuration, right click on "VirtIO Disk 1" > Remove Hardware (decide if you want to also delete the raw file that you have downloaded), Delete.
 
Now, "VirtIO Disk 1" is the only virtual storage of the VM and contains the BTRFS storage where you have installed the KDE Linux operating system. Start the VM.
 
=== Local Development ===
 
In order to speed up local builds, you can create a `mkosi.local.conf` file in the root of the repository with the following content:
 
{{Input|1=<nowiki>
[Content]
Environment=LOCALE_GEN="en_US.UTF-8 UTF-8" # replace with your locale`
Environment=MIRRORS_COUNTRY=us # replace with your country code`
Environment=PARALLEL_DOWNLOADS=50 # if your internet connection is fast
</nowiki>}}
 
You need to be using the BTRFS storage driver for docker, otherwise this won't really work.
 
If your host filesystem uses BTRFS (like KDE Linux), you can just add the following to /etc/docker/daemon.json
{{Input|1=<nowiki>
{
  "storage-driver": "btrfs"
}
</nowiki>}}


[https://docs.docker.com/engine/storage/drivers/btrfs-driver/#configure-docker-to-use-the-btrfs-storage-driver official docker documentation explaining this]
If you don't use BTRFS in your host machine, you can still create a BTRFS volume backed by a file like so:
{{Input|1=<nowiki>
systemctl stop docker.socket docker.service || true
fallocate -l 64G /store/docker.btrfs
mkfs.btrfs /store/docker.btrfs
[ -d /var/lib/docker ] || mkdir /var/lib/docker
mount /store/docker.btrfs /var/lib/docker
systemctl restart docker.socket docker.service
</nowiki>}}
Then you can run:
{{Input|1=<nowiki>
./build_docker.sh --incremental
</nowiki>}}
== Related projects ==
=== Differences from other immutable distros ===
(e.g. Kinoite, Kalpa, SteamOS)
1. '''Distributed by KDE.''' This has several advantages:
* The chain of responsibility is never gated on a third party
* KDE and KDE e.V. can have a direct relationship with third parties using it, e.g. hardware OEMs
* KDE can explicitly recommend it without "picking favorites" from among other distro partners
2. '''Relies on systemd tooling.''' This means it benefits from the bulk of development done on Systemd outside of KDE. So for example, updates use systemd-sysupdate rather than something like RPM-OStree.
3. '''No packaging knowledge required to develop it.''' Packages are used to build the base OS, but not produced or altered.
4. '''Offers multiple release schedules.''' This lets every user choose their personal preference with respect to newness vs stability. Should that preference change, switching to a different schedule is safe and painless.
=== Prior art ===
KDE neon, KDE's first version of a self-made OS. KDE neon fulfills the "distributed by KDE" requirement, but fails on the reliability angle due to the Ubuntu LTS base that ironically becomes unstable because it needs to be tinkered with to get Plasma to build on it, breaking the LTS promise.
== Roadmap ==
TODO (milestones)
== Long-term maintenance and EOL plan ==
OS images are served from https://files.kde.org/kde-linux.
The EOL contingency plan is to push a final update shipping an OS image that transforms the system into a completely different distro, to be chosen at the appropriate point in time (i.e. which distro team we have a good relationship with that could take on all the new users when the time comes).
== Governance ==
TODO
== Promotion ==
TODO (name and branding, public image, effect on relations with other distros and hardware partners)
== Communication ==
* [https://go.kde.org/matrix/#/#kde-linux:kde.org Matrix room]
* [https://invent.kde.org/kde-linux/kde-linux/-/issues Gitlab issues]
== Ideas ==
See [[KDE_Linux/Obstsalat]]
== External resources ==
* Presentation by Harald Sitter at Akademy 2024 ([https://conf.kde.org/event/6/contributions/202/attachments/135/171/The%20Operating%20System.pdf slides], [http://www.youtube.com/live/gTxRaBEUe-I?t=25936 recording]).
* https://0pointer.net/blog/fitting-everything-together.html , https://0pointer.net/blog/testing-my-system-code-in-usr-without-modifying-usr.html


== Linux® ==
== Linux® ==
The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the exclusive licensee of Linus Torvalds, owner of the mark on a world­wide basis.
The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the exclusive licensee of Linus Torvalds, owner of the mark on a world­wide basis.

Latest revision as of 16:23, 29 December 2025

"KDE Linux" (codenamed "Project Banana") is a KDE-owned general-purpose Linux®-based operating system revealed at Akademy 2024 (slides, recording), being developed at https://invent.kde.org/kde-linux. The goal of KDE Linux is to create a bulletproof OS showcasing the best of KDE that we can proudly recommend to users and OEMs, with a coherent "here's how you get it" story.

KDE Linux is an "immutable base" operating system that does not include a traditional package manager. Apps can be installed from Flatpak, Snap, or AppImages. There are various other options for getting software from other sources. System updates involve replacing the OS image with an entirely new one.

For more information, see Background information.


Current state

KDE Linux has completed its Alpha release, which includes the Testing Edition. Work now focuses on the Beta release.

The Testing Edition provides built-from-git-master versions of Plasma, KWin, and KDE apps. Getting apps from Flathub works. Developing KDE and 3rd-party software works. System Updating using Discover and the command-line works. System rollbacks work. General "daily driving" should be usable for adventurous people.

Some things don't work well yet. Notable examples include:


Getting it

Download the latest .raw image from https://files.kde.org/kde-linux/?C=M;O=D.

Verify that it arrived in one piece:

  1. Go to https://files.kde.org/kde-linux/?C=M;O=D and click "Details" for the .raw file you downloaded. Copy the long string of nonsense characters next to "SHA256". This is the SHA256 checksum of the .raw file.
  2. Once the .raw file has finished downloading, right-click on it, choose "Properties", and then click "Checksums" tab. Ensure the text field at the top is green. If it is, the file on your computer is the same one that you downloaded.

To install on physical hardware, see https://kde.org/linux/install.

To install in a virtual machine, see Installing in a virtual machine.


How to

Life on a cutting-edge immutable OS can be unfamiliar! Here's how to do various things you might be wondering about:

Hardware support

Basic use

Advanced use

Software development

Troubleshooting and debugging


Get involved

The KDE Linux team is super excited to receive new contributors! The OS is quite easy to hack on, and the developers hang out in the #kde-linux:kde.org Matrix room.

  • To propose changes, submit a Merge Request in one of the relevant git repositories.
  • To report issues in the KDE Linux operating system itself (i.e. OS design, integration, system services, etc), use invent.kde.org, and ignore the scary red banner at the top of the page.
  • To report issues in KDE Plasma or any KDE apps, use bugs.kde.org.
  • To get help with something that's not necessarily a bug, use discuss.kde.org, and tag your post with "kde-linux".


Further Reading


External Resources


Linux®

The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the exclusive licensee of Linus Torvalds, owner of the mark on a world­wide basis.

Retrieved from "https://community.kde.org/index.php?title=KDE_Linux&oldid=105459"