Migration Guide

This guide covers breaking changes between Quickshell versions and how to update your configuration.

v0.1.0 → v0.2.0

Import Syntax Changed

Old (v0.1.0):

import "folder/MyComponent.qml"

New (v0.2.0+):

import qs.folder

The qs. prefix enables module imports. Files in the imported directory become available as types.

PopupWindow Anchoring

Old (v0.1.0):

PopupWindow {
  parentWindow: panel
  x: 100
  y: 50
}

New (v0.2.0+):

PopupWindow {
  anchor.window: panel
  anchor.rect.x: 100
  anchor.rect.y: 50
}

The parentWindow, x, and y properties are deprecated in favor of anchor.window and anchor.rect.

Exclusion Zone Property

Old (v0.1.0):

PanelWindow {
  exclusionZone: 36
}

New (v0.2.0+):

PanelWindow {
  exclusionMode: ExclusionMode.Normal
  // Set zone implicitly via opposite anchors + height
  anchors { top: true; left: true; right: true }
  implicitHeight: 36
}

exclusionZone is replaced by exclusionMode and automatic zone calculation from window geometry.

v0.2.0 → v0.3.0

Singleton Syntax

Old (v0.2.0):

// WeatherService.qml
pragma Singleton
Item {
  property double temperature: 0
}

New (v0.3.0+):

// WeatherService.qml
pragma Singleton
import Quickshell

QtObject {
  property double temperature: 0
}

Singletons should now inherit QtObject instead of Item. Non-visual singletons using Item cause unnecessary rendering overhead. Import Quickshell to access QtObject.

Process API

Old (v0.2.0):

Qt.process("command arg1 arg2")

New (v0.3.0+):

Qt.process(["command", "arg1", "arg2"])

The process API now accepts an array of arguments instead of a single string. This avoids shell injection and handles arguments with spaces correctly.

Screen Property

Old (v0.2.0):

PanelWindow {
  screen: Quickshell.screens[0]
}

New (v0.3.0+):

PanelWindow {
  required property var modelData
  screen: modelData
}

When using Variants, the screen item is now assigned via modelData with required property. This follows QML best practices.

General Tips

• Always run qmllint after upgrading. It catches most syntax and type errors.
• Read the release notes on the Quickshell GitHub page for each version.
• Test in a separate config directory before migrating your main config:

  quickshell --path /tmp/test-config/shell.qml

• Check the type reference at quickshell.org/docs/types for updated property signatures.

Deprecated Features

Feature	Deprecated In	Replacement
PopupWindow.parentWindow	v0.2.0	anchor.window
PopupWindow.x / PopupWindow.y	v0.2.0	anchor.rect.x / anchor.rect.y
PanelWindow.exclusionZone	v0.2.0	exclusionMode + geometry
Qt.process(string)	v0.3.0	Qt.process(array)
Singleton inheriting Item	v0.3.0	Inherit QtObject

✅What You've Learned

• Import syntax changed from relative paths to qs. module imports
• PopupWindow anchoring moved from direct properties to anchor object
• Singletons should inherit QtObject, not Item
• Qt.process() now takes an array of arguments