Plasmoid Tutorial 1

With Plasma 5.2 out I wanted to update the tutorials on how to write a Plasmoid. Going through all of the steps from hello world, to using Plasma Components to configuration through to differing form factors.

It made sense to publish them as blog posts before I copy them to the wiki.

Behold, the first rather wordy blog post in a series of 7.


With Plasma5 we have embraced QML as our technology of choice. It is the only method of writing the UI for plasmoids.

Whilst Plasma4 offered a range of language, QML is the only way of interacting with QtQuick, the technology that powers the Plasma Shell. By using this we we get to provide a better developer experience as there is a wealth of existing QML resources. Some of the best links are:


Before you get started with writing plasmoids, it is recommended to read through the basics of these and have a bit of playing to get used to the language.

Writing plasmoids is effectively the same as writing any other QtQuick QML, with a few extensions:

  • We have a specific folder structure with metadata for our plasmashell to be able to load the files.
  • We provide a massive collection of libraries that extend the QtQuick library both with functionality and widgets that blend in with the Plasma theme.
  • Special API exists to interact with the shell, allowing you to save configurations or set default sizes.

In this series of tutorials we’ll go through the steps of writing a real plasmoid from scratch, using some of the plasma libraries.

By the end we should have a completely working, deployable RSS reader.

Hello world

Initial Folder Structure

Plasmoids follow the simple KPackage structure. In the top-most folder there should be a file titled metadata.desktop and a single folder called “contents”.

Inside the contents folder we place all our QML, assets and other additional files. We split the contents into subdirectories: config, data and ui to make things easier.

In our tutorial we will be making an RSS reader so everything is named appropriately to that.

The basic directory structure should be as follows:



[Desktop Entry]
Name=RSS Plasmoid
Comment=Shows RSS Feeds
X-KDE-PluginInfo-Author=David Edmundson

Most of the fields here should be fairly self explanatory.
If in doubt, copy this and change the relevant fields.


import QtQuick 2.0

Item {
    Text {
        anchors.centerIn: parent
        text: "Hello World!";

Providing you have followed the recommended reading this should be fairly self-explanatory, we have a text item in the middle of the plasmoid which will say “Hello World”.

Over the next few tutorials this will get somewhat larger, we will also see some of the problems with this example; here translations aren’t implemented and the text won’t match the Plasma theme colour.


From the directory above run

plasmapkg2 –install myrssplasmoid

It should now be visible in the plasmashell in the “Add widgets” option along with every other plasmoid.

We can then it to our desktop or panel like any other installed plasmoid.


Next tutorial, we will cover getting data from external sources.

  • Jeffrey Rocchio

    David, hoping you can help me. I cannot get your, or anybody’s, hello world plasmoid tutorial to work. Which seems nuts because it certainly seems very, very easy and straight-forward. In trying yours just now it won’t install. When I make the directories and files exactly as you have them, then run > plasmapkg2 –install myrssplasmoid < from terminal, in what I believe to be the right directory, it just gives me the help readout for plasmapkg2 – which incidentally also informs me that the installer has been replaced with kpackagetool5; which also doesn't work. I have been trying for days and days to just get a simple plasmoid to work, all to no avail. And online resources to help are scarce to non existent. Anything you can do to help me, including pointing me to maybe some more recent tutorials or books or something would be greatly appreciated. fwiw, I am on Fedora 27.

    • davidedmundson

      You should run it from the directory above your plasmoid. I.e

      If I have

      I would run this from /home/david

      • Jeffrey Rocchio

        Yes, I ran it from the parent directory. I actually tried it from both parent and child. But I just now did run across another reference that shows the install command using kpackagetools5 where you specify the package type, and it worked. Which is a huge milestone for me at long last. So the install command that worked is:

        kpackagetool5 -t Plasma/Applet –install myrssplasmoid

        So now I will work my way through the rest of your tutorial and see how it goes. And thanks for the quick response!