Getting Started

This guide covers installation and basic usage of pyqt-liquidglass.

Installation

Using pip

pip install pyqt-liquidglass

Using uv

uv add pyqt-liquidglass

Requirements

  • Python: 3.12 or higher

  • Operating System: macOS (functions are safe no-ops on other platforms)

  • Qt Binding: PySide6 or PyQt6

The library automatically detects your Qt binding.

Quick Start

The Three-Step Pattern

Every glass effect follows the same pattern:

  1. Prepare the window before showing

  2. Show the window

  3. Apply the glass effect

import pyqt_liquidglass as glass

# 1. Prepare before showing
glass.prepare_window_for_glass(window)

# 2. Show the window
window.show()

# 3. Apply glass after showing
glass.apply_glass_to_window(window)

Full Window Example

import sys
from PySide6.QtCore import Qt
from PySide6.QtWidgets import QApplication, QLabel, QMainWindow, QVBoxLayout, QWidget

import pyqt_liquidglass as glass


class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()
        self.setWindowTitle("Glass Demo")
        self.resize(600, 400)

        central = QWidget()
        central.setStyleSheet("background: transparent;")

        layout = QVBoxLayout(central)
        layout.setContentsMargins(40, 60, 40, 40)

        label = QLabel("Hello, Liquid Glass!")
        label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        label.setStyleSheet("""
            font-size: 28px;
            font-weight: 600;
            color: white;
            background: transparent;
        """)

        layout.addWidget(label)
        self.setCentralWidget(central)


def main() -> int:
    app = QApplication(sys.argv)

    window = MainWindow()
    glass.prepare_window_for_glass(window)
    window.show()
    glass.apply_glass_to_window(window)

    return app.exec()


if __name__ == "__main__":
    sys.exit(main())

Key Points

  • Set background: transparent on widgets that should show the glass through

  • Call prepare_window_for_glass() before show()

  • Call apply_glass_to_window() after show()

  • The window needs to be visible for the native view hierarchy to exist

Widget Glass

For applying glass to specific widgets (like sidebars):

sidebar = QWidget()
sidebar.setFixedWidth(250)
sidebar.setStyleSheet("background: transparent;")

# After window.show():
glass.apply_glass_to_widget(sidebar, options=glass.GlassOptions.sidebar())

Traffic Lights

Reposition the macOS window buttons:

glass.setup_traffic_lights_inset(window, x_offset=20, y_offset=12)

Hide or show them:

glass.hide_traffic_lights(window)
glass.show_traffic_lights(window)

Next Steps