Fixing PyQt6 Column-Based UIs: Empty QLayout Truthiness vs None Checks (QVBoxLayout/QHBoxLayout)

Learn why PyQt6 column layouts flatten: empty QLayouts evaluate False. Fix it in Python with explicit None checks to keep QVBoxLayout/QHBoxLayout intact.

Building column-based UIs in PyQt6 often looks straightforward: nest a couple of QVBoxLayout columns inside a main QHBoxLayout and add widgets into each column. Then everything stubbornly lines up in a single row. The trap usually isn’t in geometry management at all, but in how the code chooses the target layout based on a truthiness check that silently fails for empty layouts.

The setup

The intended structure is a horizontal container with two vertical columns. Widgets should stack top-to-bottom inside each column, while the columns themselves align left-to-right. The UI ends up flat because the code falls back to the main horizontal layout whenever a column layout is still empty. That fallback happens due to an innocent looking conditional that checks the layout object itself instead of explicitly testing for None.

Problematic code example

The following snippet demonstrates the issue. Names are illustrative, but the logic is the same as in the broken version: the column layouts exist, but a falsey check treats empty layouts as if they were not provided at all.

import sys
from PyQt6.QtWidgets import (QApplication, QWidget, QLabel, QLineEdit, QLayout,
                             QPushButton, QVBoxLayout, QHBoxLayout, QMessageBox)
from PyQt6.QtCore import Qt
class UiShell(QWidget):
    def __init__(self, title, w=640, h=480, row_mode=False):
        super().__init__()
        self.setWindowTitle(title)
        self.setGeometry(100, 100, w, h)
        self.root_box = QHBoxLayout() if row_mode else QVBoxLayout()
        self.setLayout(self.root_box)
        self.components_log = list()
    def push_section(self):
        column = QVBoxLayout()
        self.root_box.addLayout(column)
        return column
    def put_text(self, text, container=None):
        lab = QLabel(text)
        self.attach_item(lab, container)
        return lab
    def put_button(self, text, on_click=None, container=None):
        container = container if container else self.root_box
        btn = QPushButton(text)
        if on_click:
            btn.clicked.connect(on_click)
        self.attach_item(btn, container)
        return btn
    def attach_item(self, obj, container=None):
        container = container if container else self.root_box
        if not hasattr(container, 'items_bucket'):
            container.items_bucket = list()
        container.items_bucket.append(obj)
        container.addWidget(obj)
app = QApplication([])
win = UiShell("interface", row_mode=True)
left, right = win.push_section(), win.push_section()
win.put_text("Label 1", container=left)
win.put_button("Button 1", container=left)
win.put_text("Label 2", container=right)
win.put_button("Button 2", container=right)
win.show()
sys.exit(app.exec())

Why it happens

The core of the problem is the conditional form if container, used when a default argument might be None. In Python, conditionals evaluate the truth value of the expression. PyQt adds convenience behavior for many Qt types, including layout managers. In PyQt, a layout implements a truthiness based on its contents through the data model: layouts expose a count() method, PyQt maps that to __len__(), and an empty layout evaluates to False. The result is that if container treats an empty QLayout as falsey, even though the layout object is perfectly valid and explicitly provided. The fallback code then routes widgets into the main layout, collapsing the intended columnar structure into a single row.

The correct approach when comparing to singletons like None is to use is or is not. That avoids conflating “empty but valid” with “not provided at all”. It also matches the Python style guide recommendations and prevents subtle bugs caused by falsey-but-not-None values. Note that these convenience truthiness implementations are specific to PyQt and are not available in PySide, which is another reason to write explicit, intent-revealing conditionals.

The fix

Replace all truthiness checks that decide between “use the provided layout” and “fall back to the main layout” with explicit None comparisons. That ensures a provided, empty layout remains the target, exactly as intended.

import sys
from PyQt6.QtWidgets import (QApplication, QWidget, QLabel, QLineEdit, QLayout,
                             QPushButton, QVBoxLayout, QHBoxLayout, QMessageBox)
from PyQt6.QtCore import Qt
class UiShell(QWidget):
    def __init__(self, title, w=640, h=480, row_mode=False):
        super().__init__()
        self.setWindowTitle(title)
        self.setGeometry(100, 100, w, h)
        self.root_box = QHBoxLayout() if row_mode else QVBoxLayout()
        self.setLayout(self.root_box)
        self.components_log = list()
    def push_section(self):
        column = QVBoxLayout()
        self.root_box.addLayout(column)
        return column
    def put_text(self, text, container=None):
        lab = QLabel(text)
        self.attach_item(lab, container)
        return lab
    def put_button(self, text, on_click=None, container=None):
        if container is None:
            container = self.root_box
        btn = QPushButton(text)
        if on_click:
            btn.clicked.connect(on_click)
        self.attach_item(btn, container)
        return btn
    def attach_item(self, obj, container=None):
        if container is None:
            container = self.root_box
        if not hasattr(container, 'items_bucket'):
            container.items_bucket = list()
        container.items_bucket.append(obj)
        container.addWidget(obj)
app = QApplication([])
win = UiShell("interface", row_mode=True)
left, right = win.push_section(), win.push_section()
win.put_text("Label 1", container=left)
win.put_button("Button 1", container=left)
win.put_text("Label 2", container=right)
win.put_button("Button 2", container=right)
win.show()
sys.exit(app.exec())

Why it’s important

Layouts in PyQt can be valid objects while still evaluating to False until they contain at least one QLayoutItem. Relying on truthiness for option selection will silently reroute widgets and distort the UI. Using is None communicates intent, avoids misinterpretation of empty values, and keeps behavior predictable across code paths. It also helps when working with different Qt bindings or shims, where these convenience methods might not exist or behave differently.

Takeaway

When a parameter can be None, compare with is or is not. Do not use if x as a proxy for “was an argument provided”. With PyQt layouts this distinction is crucial: empty does not mean absent. Prefer a clear pattern such as if target is None: target = default, and the column-based UI will behave as designed.