API Reference¶

This page documents the public API of pyqt-liquidglass.

pyqt_liquidglass¶

pyqt-liquidglass: macOS Liquid Glass effects for PySide6/PyQt6.

This library provides a simple API to apply Apple’s Liquid Glass visual effects to Qt windows and widgets on macOS. On non-macOS platforms, all functions are safe no-ops that return None or False.

Basic Usage:

from PySide6.QtWidgets import QApplication, QMainWindow
import pyqt_liquidglass as glass

app = QApplication([])
window = QMainWindow()
window.setWindowTitle("Glass Demo")
window.resize(800, 600)

glass.prepare_window_for_glass(window)
window.show()

glass.apply_glass_to_window(window)
glass.setup_traffic_lights_inset(window, x_offset=20, y_offset=15)

app.exec()

Widget-specific glass (e.g., sidebar):

sidebar = QWidget()
sidebar.setFixedWidth(200)
glass.prepare_widget_for_glass(sidebar)

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

class pyqt_liquidglass.BlendingMode(*values)[source]¶

Bases: IntEnum

Blending modes for visual effect views.

These map to NSVisualEffectBlendingMode values.

BEHIND_WINDOW = 0¶

WITHIN_WINDOW = 1¶

class pyqt_liquidglass.GlassMaterial(*values)[source]¶

Bases: IntEnum

Available materials for glass effects.

These map to NSVisualEffectMaterial values for the fallback implementation on pre-macOS 26 systems.

TITLEBAR = 3¶

SELECTION = 4¶

MENU = 5¶

POPOVER = 6¶

SIDEBAR = 7¶

HEADER_VIEW = 10¶

SHEET = 11¶

WINDOW_BACKGROUND = 12¶

HUD = 13¶

FULLSCREEN_UI = 15¶

TOOLTIP = 17¶

CONTENT_BACKGROUND = 18¶

UNDER_WINDOW_BACKGROUND = 21¶

UNDER_PAGE_BACKGROUND = 22¶

class pyqt_liquidglass.GlassOptions(corner_radius: float = 0.0, material: GlassMaterial = GlassMaterial.UNDER_WINDOW_BACKGROUND, blending_mode: BlendingMode = BlendingMode.BEHIND_WINDOW, padding: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)) → None[source]¶

Bases: object

Configuration options for glass effects.

Parameters:

corner_radius (float)
material (GlassMaterial)
blending_mode (BlendingMode)
padding (tuple[float, float, float, float])

corner_radius¶: Corner radius in points for rounded glass effects. Only applies to NSGlassEffectView on macOS 26+.

material¶: The visual effect material to use. Only applies to NSVisualEffectView fallback on older macOS versions.

blending_mode¶: How the effect blends with content. Only applies to NSVisualEffectView fallback.

padding¶: Inset padding from widget edges in points (left, top, right, bottom).

corner_radius: float¶

material: GlassMaterial¶

blending_mode: BlendingMode¶

padding: tuple[float, float, float, float]¶

classmethod sidebar(*, corner_radius: float = 10.0, padding: float = 9.0) → GlassOptions[source]¶

Create options optimized for sidebar glass effects.

Parameters:

corner_radius (float) – Corner radius for rounded corners.
padding (float) – Uniform padding from all edges.

Return type:

GlassOptions

Returns:

GlassOptions configured for sidebar use.

classmethod window() → GlassOptions[source]¶

Create options for full window glass effects.

Return type:: GlassOptions
Returns:: GlassOptions configured for window-wide glass.

__init__(corner_radius: float = 0.0, material: GlassMaterial = GlassMaterial.UNDER_WINDOW_BACKGROUND, blending_mode: BlendingMode = BlendingMode.BEHIND_WINDOW, padding: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)) → None¶

Parameters:

corner_radius (float)
material (GlassMaterial)
blending_mode (BlendingMode)
padding (tuple[float, float, float, float])

Return type:

None

pyqt_liquidglass.apply_glass_to_widget(widget: QtWidgets.QWidget, options: GlassOptions | None = None) → int | None[source]¶

Apply glass effect to a specific widget.

Creates a glass effect view sized and positioned to match the widget’s geometry within its parent window.

Parameters:

widget (QWidget) – The widget to apply the glass effect to.
options (GlassOptions | None) – Glass effect configuration. Uses GlassOptions.sidebar() defaults if None.

Return type:

int | None

Returns:

An effect ID for later removal, or None if the effect could not be applied.

Note

The widget must be visible and part of a shown window. The effect view tracks widget resize and move events.

pyqt_liquidglass.apply_glass_to_window(window: PySide6.QtWidgets.QWidget, options: GlassOptions | None = None) → int | None[source]¶

Apply glass effect to an entire window.

Creates an NSGlassEffectView (macOS 26+) or NSVisualEffectView (fallback) that fills the window’s content area behind all Qt content.

Uses one of three strategies based on window configuration: 1. Sibling Injection: If root view has a superview, adds glass as sibling 2. Content Swap: For frameless windows, creates a container and swaps 3. Child Fallback: Adds glass inside root view at bottom of z-order

Parameters:

window (QWidget) – A top-level QWidget (typically QMainWindow).
options (GlassOptions | None) – Glass effect configuration. Uses defaults if None.

Return type:

int | None

Returns:

An effect ID for later removal, or None if the effect could not be applied.

Note

The window should be shown before calling this function.

pyqt_liquidglass.hide_traffic_lights(window: QtWidgets.QWidget) → bool[source]¶

Hide the traffic light buttons while keeping window functionality.

The buttons are hidden but the window remains closable, minimizable, and zoomable via keyboard shortcuts and menu commands.

Parameters:: window (QWidget) – The window whose traffic lights to hide.
Return type:: bool
Returns:: True if successful, False otherwise.

pyqt_liquidglass.prepare_widget_for_glass(widget: QtWidgets.QWidget) → None[source]¶

Prepare a widget for having glass effect applied.

Sets the necessary Qt attributes for the widget to render correctly with a glass effect behind it. The widget’s content will be visible on top of the glass effect.

Parameters:: widget (QWidget) – The widget to prepare.
Return type:: None

Note

This sets WA_TranslucentBackground which makes the widget background transparent. Ensure your widget’s stylesheet or paint event handles the transparent background appropriately.

pyqt_liquidglass.prepare_window_for_glass(window: PySide6.QtWidgets.QWidget, *, frameless: bool = False, transparent_titlebar: bool = True, full_size_content: bool = True) → None[source]¶

Prepare a window for glass effects.

Sets the necessary Qt widget attributes and configures the native NSWindow properties for glass effect rendering.

Parameters:

window (QWidget) – The window widget to prepare.
frameless (bool) – If True, remove the window frame entirely using Qt.FramelessWindowHint.
transparent_titlebar (bool) – If True, make the titlebar transparent on macOS so glass can extend underneath.
full_size_content (bool) – If True, extend content view to cover the titlebar area.

Return type:

None

Note

Call this before showing the window for best results.

pyqt_liquidglass.remove_glass_effect(effect_id: int) → bool[source]¶

Remove a previously applied glass effect.

Parameters:: effect_id (int) – The identifier returned by apply_glass_to_window or apply_glass_to_widget.
Return type:: bool
Returns:: True if the effect was successfully removed, False if the effect ID was not found.

pyqt_liquidglass.set_window_background_transparent(window: PySide6.QtWidgets.QWidget) → None[source]¶

Make a window’s background fully transparent.

This is useful when you want complete control over the window appearance, such as creating a fully custom-drawn window with glass effects.

Parameters:: window (QWidget) – The window to make transparent.
Return type:: None

Note

After calling this, the window will have no visible background. You must provide your own background through stylesheets or painting.

pyqt_liquidglass.setup_traffic_lights_inset(window: PySide6.QtWidgets.QWidget, x_offset: float = 0.0, y_offset: float = 0.0) → bool[source]¶

Reposition the traffic light buttons (close, minimize, zoom).

Uses NSLayoutConstraint to position the buttons with an offset from their default location. This method is more robust than frame-based positioning as it survives window resizes.

Parameters:

window (QWidget) – The window whose traffic lights to reposition.
x_offset (float) – Horizontal offset in points from the left edge.
y_offset (float) – Vertical offset in points from the center.

Return type:

bool

Returns:

True if the traffic lights were successfully repositioned, False otherwise.

Note

This function configures the window for full-size content view and transparent titlebar automatically.

pyqt_liquidglass.show_traffic_lights(window: PySide6.QtWidgets.QWidget) → bool[source]¶

Show previously hidden traffic light buttons.

Parameters:: window (QWidget) – The window whose traffic lights to show.
Return type:: bool
Returns:: True if successful, False otherwise.

Platform Constants¶

pyqt_liquidglass.IS_MACOS: bool: True if running on macOS, False otherwise.

pyqt_liquidglass.MACOS_VERSION: tuple[int, int, int] | None: macOS version as a tuple (major, minor, patch), or None on other platforms.

pyqt_liquidglass.HAS_GLASS_EFFECT: bool: True if NSGlassEffectView is available (macOS 26+).

pyqt_liquidglass.HAS_VISUAL_EFFECT: bool: True if NSVisualEffectView is available.