QTabWidget selected tab text blank

I'm using QTabWidget on macOS and the text of the currently selected tab is blank — it disappears when the tab has focus and only reappears when the tab loses focus. This works fine on Windows. Is there a style setting to fix this, or what's going on?

If you're working with QTabWidget on macOS and notice that the selected tab's label text vanishes while the tab is active, you're likely running into a compatibility issue between your version of PyQt and your version of macOS. This is a known problem that affected older PyQt5 releases (such as 5.9.2) on newer macOS versions (such as Big Sur / macOS 11+). The good news is that the fix is straightforward.

What causes the blank tab text?

Qt relies on native platform styles to render widgets. On macOS, this means Qt uses the macOS Aqua style to draw things like tab bars, buttons, and scroll bars. When Apple updates macOS, it can change how these native drawing APIs behave under the hood. If your version of Qt (and by extension, PyQt) hasn't been updated to account for those changes, visual glitches like invisible tab text can appear.

This particular issue — where the active tab label turns blank — was a result of running an older Qt 5.9.x build on macOS 11 (Big Sur). The Qt and PyQt libraries shipped with some package managers (like Conda) lagged behind, and that mismatch caused the rendering bug.

The fix: update your PyQt version

The simplest and most reliable fix is to update to a recent version of PyQt. If you're starting a new project today, use PyQt6, which has up-to-date macOS support. If you need to stay on PyQt5, make sure you're on at least version 5.15.2, which includes the necessary macOS compatibility fixes.

Installing PyQt6

pip install PyQt6

For detailed platform-specific instructions, see our guide on installing PyQt6 on macOS.

Or updating PyQt5 to the latest release

pip install --upgrade PyQt5

If you're working inside a Conda environment, you can still use pip to install a newer PyQt version into that environment. Just be aware that mixing Conda and pip packages can occasionally cause dependency issues, so it's worth noting what you've done in your requirements.txt or project documentation.

A quick test to confirm the fix

Here's a minimal example you can use to verify that tab labels display correctly on your system:

from PyQt6.QtWidgets import QApplication, QTabWidget, QWidget, QLabel, QVBoxLayout

app = QApplication([])

tab_widget = QTabWidget()

# Create a few simple tabs
for name in ["Hello", "Test", "Another"]:
    page = QWidget()
    layout = QVBoxLayout()
    layout.addWidget(QLabel(f"This is the {name} tab"))
    page.setLayout(layout)
    tab_widget.addTab(page, name)

tab_widget.show()

app.exec()

Run this script and click between tabs. The label on each tab should remain visible whether the tab is selected or not, in both light and dark mode. If you're new to building PyQt6 applications, our creating your first window tutorial covers the basics of setting up a window and adding widgets.

If you're on PyQt5, adjust the imports and exec call:

from PyQt5.QtWidgets import QApplication, QTabWidget, QWidget, QLabel, QVBoxLayout

app = QApplication([])

tab_widget = QTabWidget()

for name in ["Hello", "Test", "Another"]:
    page = QWidget()
    layout = QVBoxLayout()
    layout.addWidget(QLabel(f"This is the {name} tab"))
    page.setLayout(layout)
    tab_widget.addTab(page, name)

tab_widget.show()

app.exec_()

General advice for macOS rendering issues

If you ever encounter strange visual glitches on macOS — disappearing text, misaligned widgets, odd colors — the first thing to check is whether your PyQt and Qt versions are up to date. Apple makes significant changes to its rendering pipeline with major macOS releases, and the Qt project typically ships fixes in subsequent minor versions. For other macOS-specific quirks, see our notes on macOS redraw issues.

A few habits that help:

• Pin your PyQt version in requirements.txt so you know exactly what you're running. You can check your installed PyQt version to confirm what's active in your environment.
• Document any manual version overrides (like installing PyQt via pip into a Conda environment). It's easy to lose hours tracking down a problem you already solved once.
• Test on your target platform early. Cross-platform widget rendering can vary, and catching issues sooner saves time.

Keeping your Qt toolkit current is the most effective way to avoid platform-specific rendering bugs. With an up-to-date install, QTabWidget works reliably across Windows, macOS, and Linux without any special configuration.

The complete guide to packaging Python GUI applications with PyInstaller.

Get the book

[[ discount.discount_pc ]]% OFF for the next [[ discount.duration ]] [[discount.description ]] with the code [[ discount.coupon_code ]]

Purchasing Power Parity

Developers in [[ country ]] get [[ discount.discount_pc ]]% OFF on all books & courses with code [[ discount.coupon_code ]]