Python GUIs

Handling Image Drag and Drop from Web Browsers in PyQt6 — Why toLocalFile() returns an empty string and how to handle remote image drops correctly

2026-08-05T06:00:00+00:00

When dragging and dropping images from a web browser into a PyQt6 rich text editor, toLocalFile() sometimes returns a blank string. It works for some images (like Google image search results) but fails for others (like images embedded directly on a webpage). Why does this happen, and how can I handle it?

If you've added drag and drop support to your application, you may have noticed something frustrating: dragging an image from a browser sometimes works perfectly, and other times gives you nothing at all. The toLocalFile() method returns an empty string, and your image never appears.

This comes down to how browsers package image data when you start a drag operation, and what your application expects to receive. Let's walk through what's happening and how to fix it.

How drag and drop MIME data works

When you drag something — a file, an image, some text — the source application bundles that data into a QMimeData object. This object can contain several different formats at once. For example, dragging an image might include:

A file URL (text/uri-list)
Raw image data (image/png or image/jpeg)
An HTML <img> tag (text/html)
A plain text URL (text/plain)

Which of these formats are included depends entirely on the source application. Different browsers, and even different types of images within the same browser, behave differently.

Why toLocalFile() returns an empty string

The method QUrl.toLocalFile() converts a URL into a local filesystem path. It only works when the URL uses the file:// scheme — meaning the file actually exists on your computer.

When you drag an image from a Google image search, the browser often creates a temporary local file and provides a file:// URL. That's why toLocalFile() works in that case.

But when you drag an image that's embedded directly in a webpage (like a screenshot in a blog post), the browser typically provides a remote http:// or https:// URL instead. There's no local file, so toLocalFile() returns an empty string. Some browsers may also provide the image as inline data or an HTML fragment with no URL at all.

Inspecting what the browser actually sends

A good first step is to look at exactly what MIME data arrives when you drop something. This small example creates a drop target that prints out all available MIME formats and their contents:

python

import sys

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import QApplication, QLabel, QVBoxLayout, QWidget


class DropInspector(QLabel):
    def __init__(self):
        super().__init__("Drop something here")
        self.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setMinimumSize(400, 300)
        self.setStyleSheet(
            "background-color: #f0f0f0; border: 2px dashed #aaa; font-size: 16px;"
        )
        self.setAcceptDrops(True)

    def dragEnterEvent(self, event):
        event.acceptProposedAction()

    def dropEvent(self, event):
        mime_data = event.mimeData()
        print("=== Drop received ===")
        for fmt in mime_data.formats():
            data = mime_data.data(fmt)
            print(f"\nFormat: {fmt}")
            # Show first 200 bytes as text for readability.
            try:
                print(f"  Data: {bytes(data[:200]).decode('utf-8', errors='replace')}")
            except Exception:
                print(f"  Data: ({len(data)} bytes, binary)")

        if mime_data.hasUrls():
            for url in mime_data.urls():
                print(f"\nURL: {url.toString()}")
                print(f"  toLocalFile: '{url.toLocalFile()}'")
                print(f"  scheme: '{url.scheme()}'")

        event.acceptProposedAction()
        self.setText("Check console output!")


app = QApplication(sys.argv)
window = DropInspector()
window.show()
sys.exit(app.exec())

Try dragging different images from your browser into this window. You'll see that some drops include file:// URLs while others include https:// URLs or even raw image data with no URL at all.

Handling all cases in your drop event

To make your application work reliably with images dragged from any source, you need to handle multiple scenarios:

Local file URL — use the file path directly
Remote URL — download the image
Raw image data — use it directly from the MIME data
HTML with an <img> tag — extract the image URL from the HTML

Here's how to implement this step by step.

Checking for local files first

This is the simplest case and the one you likely already have working:

python

def dropEvent(self, event):
    mime_data = event.mimeData()

    if mime_data.hasUrls():
        for url in mime_data.urls():
            local_path = url.toLocalFile()
            if local_path:
                # It's a local file — use it directly.
                self.insert_image_from_path(local_path)
                event.acceptProposedAction()
                return

Handling remote URLs

When toLocalFile() returns an empty string but you still have a URL, it's likely a remote image. You can download it using Python's urllib (or requests if you prefer):

python

import os
import tempfile
import urllib.request


def download_image(url_string):
    """Download an image from a URL and return the local file path."""
    try:
        # Create a temporary file to store the downloaded image.
        suffix = os.path.splitext(url_string)[-1].split("?")[0]
        if suffix not in (".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"):
            suffix = ".png"
        tmp_file = tempfile.NamedTemporaryFile(delete=False, suffix=suffix)
        urllib.request.urlretrieve(url_string, tmp_file.name)
        return tmp_file.name
    except Exception as e:
        print(f"Failed to download image: {e}")
        return None

Then extend your drop handler:

python

if mime_data.hasUrls():
    for url in mime_data.urls():
        local_path = url.toLocalFile()
        if local_path:
            self.insert_image_from_path(local_path)
            event.acceptProposedAction()
            return

        # No local file — try downloading the remote URL.
        url_string = url.toString()
        if url_string:
            local_path = download_image(url_string)
            if local_path:
                self.insert_image_from_path(local_path)
                event.acceptProposedAction()
                return

Handling raw image data

Sometimes the browser sends the image data directly, without any URL. You can check for this using hasImage():

python

if mime_data.hasImage():
    image = mime_data.imageData()
    if image and not image.isNull():
        # Save the image to a temp file and insert it.
        tmp_path = tempfile.NamedTemporaryFile(
            delete=False, suffix=".png"
        ).name
        image.save(tmp_path)
        self.insert_image_from_path(tmp_path)
        event.acceptProposedAction()
        return

Extracting URLs from HTML

As a fallback, some drops include an HTML fragment with an <img> tag. You can parse out the src attribute:

python

import re


def extract_image_url_from_html(html):
    """Extract the first image URL from an HTML string."""
    match = re.search(r'<img[^>]+src=["\']([^"\']+)["\']', html)
    if match:
        return match.group(1)
    return None

Then add this as a final fallback:

python

if mime_data.hasHtml():
    html = mime_data.html()
    image_url = extract_image_url_from_html(html)
    if image_url:
        local_path = download_image(image_url)
        if local_path:
            self.insert_image_from_path(local_path)
            event.acceptProposedAction()
            return

Complete working example

Here's a full, working rich text editor with robust image drag and drop support. You can copy this and run it directly:

python

import os
import re
import sys
import tempfile
import urllib.request

from PyQt6.QtCore import Qt
from PyQt6.QtGui import QImage, QTextCursor
from PyQt6.QtWidgets import QApplication, QMainWindow, QTextEdit, QVBoxLayout, QWidget


def download_image(url_string):
    """Download an image from a URL and return the local file path."""
    try:
        suffix = os.path.splitext(url_string.split("?")[0])[-1]
        if suffix.lower() not in (".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"):
            suffix = ".png"
        tmp_file = tempfile.NamedTemporaryFile(delete=False, suffix=suffix)
        urllib.request.urlretrieve(url_string, tmp_file.name)
        return tmp_file.name
    except Exception as e:
        print(f"Failed to download image: {e}")
        return None


def extract_image_url_from_html(html):
    """Extract the first image URL from an HTML string."""
    match = re.search(r'<img[^>]+src=["\']([^"\']+)["\']', html)
    if match:
        return match.group(1)
    return None


class ImageDropTextEdit(QTextEdit):
    def __init__(self):
        super().__init__()
        self.setAcceptDrops(True)

    def canInsertFromMimeData(self, source):
        if source.hasImage() or source.hasUrls() or source.hasHtml():
            return True
        return super().canInsertFromMimeData(source)

    def insertFromMimeData(self, source):
        """Handle paste and drop events with image support."""
        # Try each method in order of reliability.

        # 1. Check for direct image data.
        if source.hasImage():
            image = source.imageData()
            if isinstance(image, QImage) and not image.isNull():
                self.insert_image(image)
                return

        # 2. Check for URLs (local or remote).
        if source.hasUrls():
            for url in source.urls():
                local_path = url.toLocalFile()
                if local_path and self.is_image_file(local_path):
                    self.insert_image_from_path(local_path)
                    return

                # Try downloading remote URL.
                url_string = url.toString()
                if url_string and self.looks_like_image_url(url_string):
                    local_path = download_image(url_string)
                    if local_path:
                        self.insert_image_from_path(local_path)
                        return

        # 3. Check for HTML with embedded image tags.
        if source.hasHtml():
            image_url = extract_image_url_from_html(source.html())
            if image_url:
                if image_url.startswith("data:"):
                    # Data URI — decode and insert.
                    image = self.image_from_data_uri(image_url)
                    if image and not image.isNull():
                        self.insert_image(image)
                        return
                else:
                    local_path = download_image(image_url)
                    if local_path:
                        self.insert_image_from_path(local_path)
                        return

        # Fall back to default behavior for plain text, etc.
        super().insertFromMimeData(source)

    def insert_image_from_path(self, file_path):
        """Insert an image from a local file path into the editor."""
        image = QImage(file_path)
        if image.isNull():
            print(f"Could not load image: {file_path}")
            return
        self.insert_image(image)

    def insert_image(self, image):
        """Insert a QImage into the editor at the current cursor position."""
        cursor = self.textCursor()
        document = self.document()

        # Add the image as a resource in the document.
        image_name = f"dropped_image_{id(image)}"
        document.addResource(
            document.ResourceType.ImageResource.value,
            self.create_url(image_name),
            image,
        )

        # Insert the image at the cursor.
        image_format = cursor.charFormat()
        from PyQt6.QtGui import QTextImageFormat

        img_fmt = QTextImageFormat()
        img_fmt.setName(image_name)
        img_fmt.setWidth(min(image.width(), 600))
        img_fmt.setHeight(
            int(image.height() * min(image.width(), 600) / max(image.width(), 1))
        )
        cursor.insertImage(img_fmt)

    @staticmethod
    def create_url(name):
        from PyQt6.QtCore import QUrl

        return QUrl(name)

    @staticmethod
    def is_image_file(path):
        extensions = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg"}
        return os.path.splitext(path.lower())[-1] in extensions

    @staticmethod
    def looks_like_image_url(url_string):
        """Check if a URL looks like it points to an image."""
        clean_url = url_string.split("?")[0].lower()
        extensions = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg"}
        return any(clean_url.endswith(ext) for ext in extensions)

    @staticmethod
    def image_from_data_uri(data_uri):
        """Decode a data: URI and return a QImage."""
        import base64

        try:
            # data:image/png;base64,iVBOR...
            header, data = data_uri.split(",", 1)
            image_data = base64.b64decode(data)
            image = QImage()
            image.loadFromData(image_data)
            return image
        except Exception as e:
            print(f"Failed to decode data URI: {e}")
            return None


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Rich Text Editor — Image Drop Demo")
        self.setMinimumSize(700, 500)

        self.editor = ImageDropTextEdit()
        self.editor.setPlaceholderText(
            "Try dragging an image from your web browser into this editor..."
        )

        layout = QVBoxLayout()
        layout.addWidget(self.editor)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

What's happening in the complete example

The ImageDropTextEdit class overrides insertFromMimeData, which Qt calls for both paste (Ctrl+V) and drag-and-drop operations. This gives you a single place to handle all image insertion.

The method tries each data source in order:

Direct image data — the fastest and most reliable, when available.
URLs — first checking for local files, then attempting to download remote URLs.
HTML fragments — parsing out <img> tags and fetching the referenced image, including support for data: URIs.
Fallback — if none of the above match, it passes control to the default QTextEdit behavior, so normal text paste and drop still work.

By overriding canInsertFromMimeData as well, we tell Qt's drag and drop system that our editor accepts these additional formats, which ensures the correct cursor icon appears when hovering over the editor.

This approach handles the differences between browsers — Chrome, Firefox, Edge — and between different types of images on the web, making your rich text editor's drag and drop support much more resilient.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Constantly Print Subprocess Output While Process is Running — How to stream live output from a subprocess into your PyQt6 GUI without freezing the interface

2026-07-22T06:00:00+00:00

I need to call a legacy Bash program and display the results in a Qt window. The problem is the subprocess doesn't return each output line as it happens — it waits until the entire command is finished, then dumps everything to the window at once. If the command takes a long time, the user thinks the system is frozen. How can I get live, line-by-line output from a subprocess into my Qt application?

If you've ever launched a long-running external command from a PyQt6 application and watched your entire GUI freeze until it finishes, you've hit one of the most common pitfalls in Python GUI development: blocking the event loop.

When you call subprocess.run(), Python stops and waits for the process to complete before moving on. While it's waiting, Qt's event loop — the mechanism responsible for redrawing the window, responding to clicks, and processing signals — is completely stalled. That means that the UI will not update.

There are two approaches to stream subprocess output in real time in PyQt6:

Use QProcess, which is Qt's built-in way to run external programs. It integrates directly with the event loop and emits signals as output becomes available.
Use a background QThread with Python's subprocess.Popen to read output line by line and send it back to the GUI via signals.

The wrong approach

First, let's see what happens when you use subprocess and block the event loop.

python

import subprocess
import sys

from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPlainTextEdit,
    QPushButton, QVBoxLayout, QWidget,
)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Subprocess Demo - Blocking")

        self.text_area = QPlainTextEdit()
        self.text_area.setReadOnly(True)

        self.button = QPushButton("Run Command")
        self.button.clicked.connect(self.run_command)

        layout = QVBoxLayout()
        layout.addWidget(self.text_area)
        layout.addWidget(self.button)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

    def run_command(self):
        # This blocks the entire GUI until the command finishes!
        result = subprocess.run(
            ["bash", "-c", "for i in 1 2 3 4 5; do echo Line $i; sleep 1; done"],
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
        )
        self.text_area.setPlainText(result.stdout.decode())


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Click the button, and the window becomes unresponsive for five seconds. Then all the output appears at once. The GUI didn't update during that time because subprocess.run() blocked the Qt event loop until it was finished.

Now, let's look at the two solutions to this problem:

Streaming Subprocess Output with `QProcess`

QProcess is Qt's own class for running external programs asynchronously. It starts the process and returns immediately, letting the event loop continue. As the external program produces output, QProcess emits the readyReadStandardOutput signal, which you can connect to a slot that reads and displays the new data.

This is the most "Qt-native" solution for displaying real-time subprocess output in PyQt6 and works well for many use cases. For a deeper dive into QProcess including handling stdin, managing multiple processes, and parsing output, see the complete QProcess tutorial.

python

import sys

from PyQt6.QtCore import QProcess
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPlainTextEdit,
    QPushButton, QVBoxLayout, QWidget,
)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QProcess Live Output")
        self.process = None

        self.text_area = QPlainTextEdit()
        self.text_area.setReadOnly(True)

        self.button = QPushButton("Run Command")
        self.button.clicked.connect(self.run_command)

        layout = QVBoxLayout()
        layout.addWidget(self.text_area)
        layout.addWidget(self.button)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

    def run_command(self):
        if self.process is not None:
            return  # Already running

        self.text_area.clear()
        self.button.setEnabled(False)

        self.process = QProcess(self)
        self.process.readyReadStandardOutput.connect(self.handle_stdout)
        self.process.readyReadStandardError.connect(self.handle_stderr)
        self.process.finished.connect(self.process_finished)

        # QProcess takes the program and arguments separately.
        # To run a bash command, pass "-c" and the command string as arguments.
        self.process.start(
            "bash",
            ["-c", "for i in 1 2 3 4 5; do echo \"Line $i\"; sleep 1; done"],
        )

    def handle_stdout(self):
        data = self.process.readAllStandardOutput()
        text = bytes(data).decode("utf-8")
        self.text_area.appendPlainText(text.rstrip())

    def handle_stderr(self):
        data = self.process.readAllStandardError()
        text = bytes(data).decode("utf-8")
        self.text_area.appendPlainText(text.rstrip())

    def process_finished(self):
        self.text_area.appendPlainText("--- Process finished ---")
        self.process = None
        self.button.setEnabled(True)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Run this, click the button, and you'll see each line appear one at a time, with the GUI remaining fully responsive throughout.

How `QProcess` Streams Output in Real Time

When you call self.process.start(), the external command begins running in the background. Qt's event loop keeps spinning, so your window stays responsive.

Each time the external process writes to stdout, QProcess emits readyReadStandardOutput. The connected slot (handle_stdout) reads the available data and appends it to the text area. The same pattern applies for stderr.

When the process exits, the finished signal fires, and we clean up.

Running Complex Bash Commands with `QProcess`

If your actual command involves sourcing setup files, changing directories, and running build tools — like in the original question — you can pass the entire sequence as a single string to bash -c:

python

command = (
    "source /path/to/setup_file -r && "
    "cd /path/to/parent_directory && "
    "build_project_command"
)
self.process.start("bash", ["-c", command])

This works because bash -c accepts the whole pipeline as one argument.

Streaming Subprocess Output Using `QThread` and `subprocess.Popen`

Sometimes QProcess doesn't quite fit your needs. For example, you might need to do additional processing on each line of output before displaying it, or you might need to integrate with Python libraries that expect a file-like object. In these cases, running subprocess.Popen in a background QThread is a good alternative.

The idea: spin up a QThread that runs the subprocess, reads its output line by line, and emits a signal for each line. The main thread receives those signals and updates the GUI safely. If you're new to threading in PyQt6, our guide to multithreading with QThreadPool covers the fundamentals of running background tasks without freezing the GUI.

python

import subprocess
import sys

from PyQt6.QtCore import QThread, pyqtSignal
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPlainTextEdit,
    QPushButton, QVBoxLayout, QWidget,
)


class SubprocessWorker(QThread):
    """Runs a subprocess in a background thread and emits output line by line."""

    output_line = pyqtSignal(str)
    finished_signal = pyqtSignal(int)  # exit code

    def __init__(self, command):
        super().__init__()
        self.command = command

    def run(self):
        process = subprocess.Popen(
            self.command,
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            text=True,
            bufsize=1,  # Line-buffered
        )

        for line in process.stdout:
            self.output_line.emit(line.rstrip())

        process.wait()
        self.finished_signal.emit(process.returncode)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QThread + Subprocess Live Output")
        self.worker = None

        self.text_area = QPlainTextEdit()
        self.text_area.setReadOnly(True)

        self.button = QPushButton("Run Command")
        self.button.clicked.connect(self.run_command)

        layout = QVBoxLayout()
        layout.addWidget(self.text_area)
        layout.addWidget(self.button)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

    def run_command(self):
        if self.worker is not None:
            return

        self.text_area.clear()
        self.button.setEnabled(False)

        self.worker = SubprocessWorker(
            ["bash", "-c", "for i in 1 2 3 4 5; do echo \"Line $i\"; sleep 1; done"]
        )
        self.worker.output_line.connect(self.on_output_line)
        self.worker.finished_signal.connect(self.on_finished)
        self.worker.start()

    def on_output_line(self, text):
        self.text_area.appendPlainText(text)

    def on_finished(self, exit_code):
        self.text_area.appendPlainText(f"--- Process finished (exit code {exit_code}) ---")
        self.worker = None
        self.button.setEnabled(True)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

How `QThread` with `subprocess.Popen` Works

subprocess.Popen (unlike subprocess.run) starts the process and returns immediately, giving you a handle to interact with it. By iterating over process.stdout, you get each line as it's produced.

Because this iteration is blocking (it waits for the next line), we run it in a QThread so it doesn't block the GUI. Each time a line arrives, the worker emits output_line, which is safely delivered to the main thread via Qt's signal-slot mechanism.

Setting bufsize=1 and text=True enables line-buffered mode, which means output is available to read as soon as a newline character is written by the subprocess.

Fixing Delayed Subprocess Output: Buffering Issues

Even with both approaches working correctly on the Qt side, you might still see delayed output if the external program itself buffers its stdout. Many programs buffer output differently when they detect they're writing to a pipe (which is what happens with both QProcess and subprocess.Popen) versus writing to a terminal.

If your external program supports it, you can try:

Setting the PYTHONUNBUFFERED=1 environment variable (for Python scripts).
Using stdbuf -oL to force line-buffered output: stdbuf -oL your_command.
Using script or unbuffer (from the expect package) to trick the program into thinking it's connected to a terminal.

For example, with the QProcess approach:

python

self.process.start(
    "bash",
    ["-c", "stdbuf -oL your_long_running_command"],
)

`QProcess` vs `QThread`: Which Approach Should You Use?

Use QProcess when you're running a simple external command and want a clean, Qt-integrated solution. It handles the event loop integration for you, supports signals for stdout, stderr, and process completion, and doesn't require managing threads.

Use a background QThread when you need more control over how you read the output — for example, if you want to parse each line, filter output, or interact with the subprocess's stdin in complex ways. The thread approach also makes it straightforward to use Python's subprocess module features that don't have direct equivalents in QProcess.

Both approaches keep the GUI responsive and deliver output in real time. Pick whichever fits your situation best.

Complete Example: Live Build Output Viewer in PyQt6

Here's a more polished example that combines the QProcess approach with a few usability improvements — a scrolling output view, a status indicator, and support for running a configurable command. This example uses layouts and basic widgets to build the interface:

python

import sys

from PyQt6.QtCore import QProcess
from PyQt6.QtGui import QFont
from PyQt6.QtWidgets import (
    QApplication, QHBoxLayout, QLabel, QLineEdit,
    QMainWindow, QPlainTextEdit, QPushButton,
    QVBoxLayout, QWidget,
)


class BuildOutputViewer(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Live Build Output Viewer")
        self.resize(700, 500)
        self.process = None

        # Command input
        self.command_input = QLineEdit()
        self.command_input.setPlaceholderText(
            "Enter bash command, e.g.: for i in $(seq 1 10); do echo Building step $i; sleep 0.5; done"
        )
        self.command_input.setText(
            "for i in $(seq 1 10); do echo \"Building step $i...\"; sleep 0.5; done && echo Done!"
        )

        # Output area
        self.output_area = QPlainTextEdit()
        self.output_area.setReadOnly(True)
        self.output_area.setFont(QFont("Courier", 10))
        self.output_area.setStyleSheet(
            "QPlainTextEdit { background-color: #1e1e1e; color: #d4d4d4; }"
        )

        # Buttons and status
        self.run_button = QPushButton("Run")
        self.run_button.clicked.connect(self.start_process)

        self.stop_button = QPushButton("Stop")
        self.stop_button.clicked.connect(self.stop_process)
        self.stop_button.setEnabled(False)

        self.status_label = QLabel("Ready")

        button_layout = QHBoxLayout()
        button_layout.addWidget(self.run_button)
        button_layout.addWidget(self.stop_button)
        button_layout.addWidget(self.status_label)
        button_layout.addStretch()

        layout = QVBoxLayout()
        layout.addWidget(self.command_input)
        layout.addLayout(button_layout)
        layout.addWidget(self.output_area)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

    def start_process(self):
        command = self.command_input.text().strip()
        if not command:
            return

        self.output_area.clear()
        self.run_button.setEnabled(False)
        self.stop_button.setEnabled(True)
        self.status_label.setText("Running...")

        self.process = QProcess(self)
        self.process.readyReadStandardOutput.connect(self.handle_stdout)
        self.process.readyReadStandardError.connect(self.handle_stderr)
        self.process.finished.connect(self.process_finished)

        self.process.start("bash", ["-c", command])

    def stop_process(self):
        if self.process is not None:
            self.process.kill()

    def handle_stdout(self):
        data = self.process.readAllStandardOutput()
        text = bytes(data).decode("utf-8")
        self.output_area.appendPlainText(text.rstrip())

    def handle_stderr(self):
        data = self.process.readAllStandardError()
        text = bytes(data).decode("utf-8")
        self.output_area.appendPlainText(text.rstrip())

    def process_finished(self, exit_code, exit_status):
        status_text = "Finished" if exit_code == 0 else f"Exited with code {exit_code}"
        self.status_label.setText(status_text)
        self.run_button.setEnabled(True)
        self.stop_button.setEnabled(False)
        self.process = None


app = QApplication(sys.argv)
window = BuildOutputViewer()
window.show()
app.exec()

This gives you a terminal-styled output viewer where you can type in a command, run it, watch the output stream in line by line, and stop it if needed — all without the GUI ever locking up.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Why Widgets Appear as Separate Windows — Understanding widget parenting in Qt and how to fix widgets that float outside your main window

2026-07-08T06:00:00+00:00

Sometimes when I dynamically add widgets to tabs in my PyQt6 application, they pop out as windows instead. What's going on?

If you're dynamically adding widgets to your PyQt6 application and finding that they pop out as separate floating windows instead of appearing neatly inside your application, you're running into one of Qt's gotchas: widget parenting.

This problem usually shows up when widgets are added from a callback, event listener or signal handler. But there are a million different ways to screw this up. Let's look at why this happens and how to fix it.

How Qt decides what's a window

In Qt, every widget can optionally have a parent widget. The parent determines where a widget lives visually — a widget with a parent is drawn inside that parent. A widget without a parent becomes a top-level window, floating independently on your desktop.

This is the root cause of widgets appearing outside your main window. When you create a widget and it doesn't have a parent — either because you didn't set one, or because the parent was lost somehow — Qt treats it as a standalone window.

Here are the most common reasons widgets end up floating:

Creating widgets without a parent

python

# This widget has no parent — it will be a floating window
tabs = QTabWidget()

# This widget has a parent — it will appear inside parent_widget
tabs = QTabWidget(parent_widget)

When you add a widget to a layout, the layout assigns the parent automatically. But if something goes wrong between creation and layout insertion (like an exception, or the widget being shown prematurely), the widget stays parentless.

The safest approach is to pass a parent when creating widgets:

python

def create_new_tab(self):
    wdg = QWidget()
    layout = QGridLayout(wdg)

    tabs = QTabWidget(wdg)  # Explicitly set parent
    tab1 = QWidget(tabs)     # Explicitly set parent
    tab2 = QWidget(tabs)     # Explicitly set parent
    tabs.addTab(tab1, "Start")
    tabs.addTab(tab2, "Profile")
    layout.addWidget(tabs)

    return wdg

...although, honestly, I don't usually bother. If I know I'll be adding a widget to a layout immediately, I'll omit the parent assignment.

In an window __init__ the safety question is less relevant because, if there is an unhandled exception that blocks the adding your sub-widget to a layout, it will also block the creation of the parent window.

Accidentally recreating a widget

If you have a tab widget stored as self.w and somewhere in your code you do:

python

self.w = QTabWidget()

...the original tab widget is replaced. If the old widget gets garbage collected, all the tabs that had it as their parent suddenly become orphans — parentless widgets that float as independent windows.

Be careful not to reassign widget attributes unintentionally, especially in callbacks that might run multiple times.

Losing the parent reference

If you explicitly set a widget's parent to None, it becomes a top-level window:

python

widget.setParent(None)  # This widget is now a floating window

This sometimes happens indirectly. For example, removing a widget from a layout in certain ways can clear its parent.

A clean approach to dynamic tabs

Here's a complete, working example that dynamically adds tabs without any floating-window issues. It demonstrates the correct way to set up a QTabWidget with a "+" button that adds new tabs:

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QTabWidget,
    QWidget, QVBoxLayout, QLabel
)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Dynamic Tabs")
        self.setFixedSize(600, 400)

        self.tabs = QTabWidget(self)
        self.tabs.currentChanged.connect(self.on_tab_changed)

        # Add an initial tab
        self.add_content_tab("Tab 1")

        # Add the "+" tab for creating new tabs
        self.tabs.addTab(QWidget(self.tabs), "+")

        self.setCentralWidget(self.tabs)

    def on_tab_changed(self, index):
        # Check if the "+" tab was clicked
        if self.tabs.tabText(index) == "+":
            self.add_new_tab()

    def add_new_tab(self):
        # Count existing content tabs (exclude the "+" tab)
        tab_count = self.tabs.count()  # includes "+"
        new_title = f"Tab {tab_count}"

        # Insert the new tab before the "+" tab
        new_tab = self.create_tab_content(new_title)
        insert_index = self.tabs.count() - 1
        self.tabs.insertTab(insert_index, new_tab, new_title)

        # Switch to the newly created tab (avoid retriggering)
        self.tabs.blockSignals(True)
        self.tabs.setCurrentIndex(insert_index)
        self.tabs.blockSignals(False)

    def add_content_tab(self, title):
        """Add a content tab before the + tab."""
        tab = self.create_tab_content(title)
        # Insert before the last tab if "+" exists, otherwise just add
        plus_index = None
        for i in range(self.tabs.count()):
            if self.tabs.tabText(i) == "+":
                plus_index = i
                break

        if plus_index is not None:
            self.tabs.insertTab(plus_index, tab, title)
        else:
            self.tabs.addTab(tab, title)

    def create_tab_content(self, title):
        """Create the widget content for a tab."""
        widget = QWidget(self.tabs)  # Parent is the tab widget
        layout = QVBoxLayout(widget)
        label = QLabel(f"Content for {title}", widget)
        layout.addWidget(label)
        return widget


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

A few things to notice in this example:

The main window inherits from QMainWindow, and QApplication is created separately.
Every widget is created with an explicit parent: QWidget(self.tabs), QLabel(text, widget), etc.
blockSignals(True) is used when programmatically changing the current tab to prevent the currentChanged signal from firing recursively.
New tabs are inserted before the "+" tab using insertTab, so the "+" always stays at the end.

Summary

Widget parenting is one of those things in Qt that works invisibly when everything is correct — and causes confusing visual glitches the moment something is slightly off. The good news is that once you understand the pattern, the fix is almost always the same: make sure every widget has a parent.

If you're new to PyQt6, our guide to creating your first window covers the basics of setting up a QMainWindow, while the widgets tutorial walks through the most common widgets and how to use them correctly.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Set Row Background Colors in a QTableView — Use Qt's BackgroundRole to color entire rows based on your data

2026-06-10T06:00:00+00:00

I have a QTableView table showing some data about connected devices. How can I highlight rows to give a visual indicator of the current status of the device?

When you're working with a QTableView and a custom model, it's common to want to highlight entire rows based on some condition in your data. For example, you might want to color a row blue when a device has a connected status, or red when something has gone wrong.

Understanding How `data()` Works

In Qt's Model/View architecture, the view calls your model's data() method for every cell in the table — and for each cell, it asks about multiple roles. One of those roles is Qt.BackgroundRole, which tells the view what background color to use for that cell.

The view asks for Qt.BackgroundRole on every single cell, not just one column. So if your data() method returns a color for Qt.BackgroundRole based on the row data (ignoring the column), the color will be applied to every cell in that row.

Let's build a working example.

A Complete Working Example

Here's a full example you can run directly. It creates a QTableView with colored rows based on the PRESENT_STATUS field in each row of data:

python

import sys
from typing import Union

from PyQt6.QtCore import QAbstractTableModel, QModelIndex, Qt
from PyQt6.QtGui import QColor
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView


class TableModel(QAbstractTableModel):

    def __init__(self, data: Union[list, None] = None):
        super().__init__()
        self._data = data or []
        self._hdr = self._gen_hdr_data() if data else []
        self._base_color = {
            "NewConnection": QColor("blue"),
            "Registered": QColor("green"),
        }

    def _gen_hdr_data(self):
        """Build a sorted list of all unique keys across all row dicts."""
        all_keys = set()
        for d in self._data:
            all_keys.update(d.keys())
        return sorted(all_keys)

    def rowCount(self, parent=QModelIndex()):
        return len(self._data)

    def columnCount(self, parent=QModelIndex()):
        return len(self._hdr)

    def headerData(self, section, orientation, role):
        if role == Qt.DisplayRole and orientation == Qt.Horizontal:
            return self._hdr[section]

    def data(self, index: QModelIndex, role: int):
        if not index.isValid():
            return None

        row_dict = self._data[index.row()]
        state = row_dict.get("PRESENT_STATUS", "")

        if role == Qt.DisplayRole:
            col_key = self._hdr[index.column()]
            value = row_dict.get(col_key, "")
            return str(value) if value else ""

        if role == Qt.BackgroundRole:
            color = self._base_color.get(state)
            if color:
                return color

        return None


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Row Background Colors in QTableView")

        data = [
            {"IP": "192.168.1.10", "PRESENT_STATUS": "NewConnection"},
            {"IP": "192.168.1.108", "FORMER_STATUS": "NewConnection",
             "PRESENT_STATUS": "Registered"},
            {"IP": "192.168.1.50", "PRESENT_STATUS": "Unknown"},
        ]

        self.table = QTableView()
        model = TableModel(data)
        self.table.setModel(model)
        self.setCentralWidget(self.table)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

The method that Qt calls on the model is called data, so in the example above, the list is stored as self._data (with a leading underscore) to avoid this.

Run this and you'll see three rows. The first row ("NewConnection") has a blue background, the second row ("Registered") has a green background, and the third row ("Unknown") has no special coloring because it isn't in the _base_color dictionary.

How Colors are Set on Rows

To understand how the color is being set to the entire row, take a look at the Qt.BackgroundRole section of data():

python

if role == Qt.BackgroundRole:
    color = self._base_color.get(state)
    if color:
        return color

Notice that index.column() isn't used here at all. The color decision is based entirely on the row's PRESENT_STATUS value. Since the view calls data() for every cell in the row — column 0, column 1, column 2, etc. — and each call gets the same color back, the entire row ends up painted.

If you only wanted to color a specific column (say, just the status column), you would add a column check:

python

if role == Qt.BackgroundRole:
    # Only color the PRESENT_STATUS column
    if self._hdr[index.column()] == "PRESENT_STATUS":
        color = self._base_color.get(state)
        if color:
            return color

Making the Text Readable

One thing you'll notice with a dark background color like blue is that the default black text becomes hard to read. You can fix this by also handling Qt.ForegroundRole and returning a light text color when the background is dark:

python

def data(self, index: QModelIndex, role: int):
    if not index.isValid():
        return None

    row_dict = self._data[index.row()]
    state = row_dict.get("PRESENT_STATUS", "")

    if role == Qt.DisplayRole:
        col_key = self._hdr[index.column()]
        value = row_dict.get(col_key, "")
        return str(value) if value else ""

    if role == Qt.BackgroundRole:
        color = self._base_color.get(state)
        if color:
            return color

    if role == Qt.ForegroundRole:
        # If this row has a background color, use white text.
        if state in self._base_color:
            return QColor("white")

    return None

Now blue and green rows will have white text, making everything easy to read.

Updating Colors Dynamically

If your data changes at runtime — for example, a device's status changes from "NewConnection" to "Registered" — you need to tell the view that something has changed so it repaints. You do this by emitting the dataChanged signal:

python

def update_status(self, row, new_status):
    self._data[row]["PRESENT_STATUS"] = new_status
    # Emit dataChanged for the entire row.
    top_left = self.index(row, 0)
    bottom_right = self.index(row, self.columnCount() - 1)
    self.dataChanged.emit(top_left, bottom_right)

This tells the view to re-query data() for every cell in that row, which picks up both the new display text and the new background color. For a deeper look at how signals work to keep your model and view in sync, see Signals, Slots & Events.

Summary

Once you understand how the model's data() method works, coloring entire rows in a QTableView is relatively straightforward. The view asks for each role on every cell, so returning a color from Qt.BackgroundRole based on row-level data — without filtering by column — naturally paints the whole row. Pair that with Qt.ForegroundRole for readable text, and you've got a clean, data-driven way to highlight rows in your table.

To learn more about using QTableView with custom models and data from numpy or pandas, see the QTableView with numpy and pandas tutorial. If you want to add sorting and filtering to your table, take a look at Sorting and Filtering Tables.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Authentication and Authorization with PyQt6 or PySide6 — Secure your desktop applications with login flows, token-based auth, and role-based access control

2026-06-03T06:00:00+00:00

How can I add authentication and authorization to a PyQt6 application? Is there something built into Qt to make this easier?

When you build a desktop application with PyQt6 or PySide6, sooner or later you'll need to control who can use it and what they can do. Maybe your app connects to a cloud service. Maybe certain features should only be available to administrators. Either way, you need authentication (verifying who the user is) and authorization (deciding what they're allowed to do).

Qt doesn't provide a built-in authentication framework. But that's fine. You can combine Qt's capabilities with Python's networking and security tools to build a solid auth flow for your application.

In this tutorial, we'll walk through the full process: creating a login dialog, authenticating against a remote server, handling tokens, and enabling or disabling parts of your UI based on a user's role.

Approaches to Authentication in Desktop Apps

Before writing any code, it helps to understand the options available when securing a desktop application. The right approach depends on how much security you need and what infrastructure you have.

Simple login check Your app sends credentials to a remote server at startup. If authentication fails, you disable the UI (partially or entirely). This deters casual users, but a determined hacker could modify the client to bypass the check.
Token-based unlock After a successful login, the server returns a token or key that unlocks functionality in the app. Without the token, the app can't perform certain operations. This is more secure — the app is genuinely non-functional without a valid token — though once data is decoded into memory, it's theoretically still accessible.
Server-side execution After authentication, the app sends work to the server, which performs the actual operations. The sensitive logic never runs on the client at all. This is the most secure approach, but it requires server infrastructure to handle the workload.

In the Server-side execution model, the work done on the server doesn't necessarily need to be complex. Transforming or pre-processing some data from one format to another will be enough to deter most attempts at circumvention. However, it's common to to use this technique to hide the algorithmic "secret sauce" completely.

For most applications, the middle ground — authenticating against a remote API and using the returned token to gate access — provides a good balance of security and simplicity. That's what we'll build here.

Your app shouldn't care about the database directly. Instead, it should talk to an API (Application Programming Interface) on your server. The API handles user lookups, password verification, and token generation. Your desktop app just sends HTTP requests and processes the responses.

Setting Up a Simple Auth Server (For Testing)

To test our client application, we need something to authenticate against. We'll create a minimal Flask server that accepts login requests and returns a JSON Web Token (JWT). In a real project, this would be your existing backend, but having a self-contained example makes it easier to experiment.

Install the dependencies for the server:

pip install flask pyjwt

Here's a minimal auth server:

python

import datetime

import jwt
from flask import Flask, jsonify, request

app = Flask(__name__)
SECRET_KEY = "your-secret-key-change-this"

# In production, use a real database with hashed passwords.
USERS = {
    "admin": {"password": "admin123", "role": "admin"},
    "viewer": {"password": "viewer123", "role": "viewer"},
}


@app.route("/auth/login", methods=["POST"])
def login():
    data = request.get_json()
    username = data.get("username", "")
    password = data.get("password", "")

    user = USERS.get(username)
    if user and user["password"] == password:
        token = jwt.encode(
            {
                "username": username,
                "role": user["role"],
                "exp": datetime.datetime.utcnow()
                + datetime.timedelta(hours=1),
            },
            SECRET_KEY,
            algorithm="HS256",
        )
        return jsonify(
            {"token": token, "role": user["role"], "username": username}
        )

    return jsonify({"error": "Invalid credentials"}), 401


@app.route("/auth/verify", methods=["GET"])
def verify():
    auth_header = request.headers.get("Authorization", "")
    if not auth_header.startswith("Bearer "):
        return jsonify({"error": "Missing token"}), 401

    token = auth_header.split(" ", 1)[1]
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        return jsonify(
            {"username": payload["username"], "role": payload["role"]}
        )
    except jwt.ExpiredSignatureError:
        return jsonify({"error": "Token expired"}), 401
    except jwt.InvalidTokenError:
        return jsonify({"error": "Invalid token"}), 401


if __name__ == "__main__":
    app.run(port=5000, debug=True)

Save this as auth_server.py and run it in a separate terminal:

python auth_server.py

The server exposes two endpoints:

POST /auth/login — accepts a JSON body with username and password, returns a JWT token.
GET /auth/verify — accepts an Authorization: Bearer <token> header and returns the user info if the token is valid.

This server stores passwords in plain text and uses a hardcoded secret key. In production, you'd hash passwords (using bcrypt or similar) and store the secret key securely. This is purely for demonstration.

Now let's build the PyQt6 side. We'll start with a login dialog — a modal window where the user enters their credentials. If you're new to dialogs in Qt, see our tutorial on creating dialogs in PyQt6 for a thorough introduction.

Install the client dependencies:

pip install PyQt6 requests

If you're using PySide6, replace from PyQt6.QtWidgets import ... with from PySide6.QtWidgets import ... (and similarly for other Qt modules). The rest of the code is identical.

python

from PyQt6.QtCore import Qt
from PyQt6.QtWidgets import (
    QDialog,
    QFormLayout,
    QLabel,
    QLineEdit,
    QPushButton,
    QVBoxLayout,
)


class LoginDialog(QDialog):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("Login")
        self.setFixedSize(350, 200)

        layout = QVBoxLayout()

        self.form_layout = QFormLayout()

        self.username_input = QLineEdit()
        self.username_input.setPlaceholderText("Enter your username")
        self.form_layout.addRow("Username:", self.username_input)

        self.password_input = QLineEdit()
        self.password_input.setPlaceholderText("Enter your password")
        self.password_input.setEchoMode(QLineEdit.Password)
        self.form_layout.addRow("Password:", self.password_input)

        layout.addLayout(self.form_layout)

        self.login_button = QPushButton("Login")
        self.login_button.clicked.connect(self.accept)
        layout.addWidget(self.login_button)

        self.status_label = QLabel("")
        self.status_label.setAlignment(Qt.AlignCenter)
        self.status_label.setStyleSheet("color: red;")
        layout.addWidget(self.status_label)

        self.setLayout(layout)

        # Allow pressing Enter to submit.
        self.password_input.returnPressed.connect(self.login_button.click)
        self.username_input.returnPressed.connect(
            self.password_input.setFocus
        )

    def get_credentials(self):
        return (
            self.username_input.text().strip(),
            self.password_input.text(),
        )

    def set_status(self, message):
        self.status_label.setText(message)

This dialog inherits from QDialog, which gives us the modal behavior we need — when shown with .exec_(), it blocks interaction with the rest of the application until the user either logs in or closes the dialog.

The get_credentials method returns the entered username and password as a tuple. The set_status method lets us display error messages (like "Invalid credentials") directly in the dialog.

Creating an Auth Manager

Rather than scattering authentication logic throughout the application, we'll encapsulate it in a dedicated class. This AuthManager handles login requests, stores the token, and provides the user's role.

python

import requests


class AuthManager:
    def __init__(self, base_url="http://localhost:5000"):
        self.base_url = base_url
        self.token = None
        self.username = None
        self.role = None

    def login(self, username, password):
        """
        Attempt to log in. Returns True on success, False on failure.
        Raises an exception on network errors.
        """
        response = requests.post(
            f"{self.base_url}/auth/login",
            json={"username": username, "password": password},
            timeout=10,
        )

        if response.status_code == 200:
            data = response.json()
            self.token = data["token"]
            self.username = data["username"]
            self.role = data["role"]
            return True

        return False

    def is_authenticated(self):
        return self.token is not None

    def get_auth_header(self):
        """Return headers dict with the Bearer token for API requests."""
        if self.token:
            return {"Authorization": f"Bearer {self.token}"}
        return {}

    def has_role(self, role):
        return self.role == role

    def logout(self):
        self.token = None
        self.username = None
        self.role = None

The get_auth_header method is especially useful. Once a user has logged in, you can include this header in any subsequent API call to prove that the request is coming from an authenticated user:

python

response = requests.get(
    "http://localhost:5000/some/protected/endpoint",
    headers=auth_manager.get_auth_header(),
    timeout=10,
)

Now we connect the login dialog to the auth manager. The pattern is: show the dialog, grab the credentials, try to authenticate, and either proceed to the main window or show an error.

python

import sys

from PyQt6.QtWidgets import QApplication, QMessageBox


def attempt_login(auth_manager):
    """
    Show the login dialog repeatedly until the user either
    successfully authenticates or cancels.
    Returns True on successful login, False if cancelled.
    """
    dialog = LoginDialog()

    while True:
        result = dialog.exec_()

        if result != QDialog.Accepted:
            # User closed the dialog or pressed Cancel.
            return False

        username, password = dialog.get_credentials()

        if not username or not password:
            dialog.set_status("Please enter both fields.")
            continue

        try:
            if auth_manager.login(username, password):
                return True
            else:
                dialog.set_status("Invalid username or password.")
        except requests.exceptions.ConnectionError:
            dialog.set_status("Cannot connect to server.")
        except requests.exceptions.Timeout:
            dialog.set_status("Connection timed out.")
        except requests.exceptions.RequestException as e:
            dialog.set_status(f"Error: {e}")

This function keeps showing the login dialog until either the login succeeds or the user dismisses it. Network errors are caught and displayed in the dialog, so the user gets useful feedback without the app crashing.

Building the Main Window with Role-Based Access

The main window of our application will show different features depending on the user's role. Admin users see everything; viewers have a restricted experience. We'll use actions, toolbars, and menus to structure the interface.

python

from PyQt6.QtWidgets import (
    QAction,
    QMainWindow,
    QMenu,
    QMenuBar,
    QStatusBar,
    QTextEdit,
    QToolBar,
)


class MainWindow(QMainWindow):
    def __init__(self, auth_manager):
        super().__init__()
        self.auth_manager = auth_manager

        self.setWindowTitle("My Application")
        self.setMinimumSize(600, 400)

        # Central widget.
        self.text_edit = QTextEdit()
        self.setCentralWidget(self.text_edit)

        # Menu bar.
        menu_bar = self.menuBar()

        file_menu = menu_bar.addMenu("&File")

        self.save_action = QAction("&Save", self)
        self.save_action.triggered.connect(self.save_document)
        file_menu.addAction(self.save_action)

        file_menu.addSeparator()

        logout_action = QAction("&Logout", self)
        logout_action.triggered.connect(self.handle_logout)
        file_menu.addAction(logout_action)

        quit_action = QAction("&Quit", self)
        quit_action.triggered.connect(self.close)
        file_menu.addAction(quit_action)

        # Admin-only menu.
        self.admin_menu = menu_bar.addMenu("&Admin")

        manage_users_action = QAction("&Manage Users", self)
        manage_users_action.triggered.connect(self.manage_users)
        self.admin_menu.addAction(manage_users_action)

        server_settings_action = QAction("&Server Settings", self)
        server_settings_action.triggered.connect(self.server_settings)
        self.admin_menu.addAction(server_settings_action)

        # Status bar.
        self.status_bar = QStatusBar()
        self.setStatusBar(self.status_bar)

        # Apply role-based restrictions.
        self.apply_permissions()

    def apply_permissions(self):
        """Enable or disable UI elements based on the user's role."""
        role = self.auth_manager.role
        username = self.auth_manager.username

        self.status_bar.showMessage(
            f"Logged in as {username} ({role})"
        )

        if role == "admin":
            # Admins get full access.
            self.admin_menu.setEnabled(True)
            self.save_action.setEnabled(True)
            self.text_edit.setReadOnly(False)
        elif role == "viewer":
            # Viewers can see content but not edit or access admin.
            self.admin_menu.setEnabled(False)
            self.save_action.setEnabled(False)
            self.text_edit.setReadOnly(True)
            self.text_edit.setPlaceholderText(
                "You have read-only access."
            )
        else:
            # Unknown role: disable everything as a safe default.
            self.admin_menu.setEnabled(False)
            self.save_action.setEnabled(False)
            self.text_edit.setReadOnly(True)

    def save_document(self):
        QMessageBox.information(
            self, "Save", "Document saved (placeholder)."
        )

    def manage_users(self):
        QMessageBox.information(
            self, "Admin", "User management (placeholder)."
        )

    def server_settings(self):
        QMessageBox.information(
            self, "Admin", "Server settings (placeholder)."
        )

    def handle_logout(self):
        self.auth_manager.logout()
        self.close()

The apply_permissions method is where authorization happens. After a successful login, we check the user's role and adjust the UI accordingly. Disabled menu items are grayed out and non-clickable, and the text editor is set to read-only for viewers.

This approach — enabling and disabling widgets based on roles — is the standard pattern for authorization in desktop apps. You can extend it as far as you need: hide entire toolbar sections, show different pages in a stacked widget, or restrict access to specific actions.

Making Authenticated API Requests

Once a user is logged in, you'll often need to make further API calls — fetching data, submitting forms, etc. Each of these requests should include the authentication token so the server can verify the user. For long-running API calls, consider using multithreading with QThreadPool to keep the UI responsive while waiting for server responses.

Here's how you might fetch some protected data:

python

def fetch_protected_data(auth_manager):
    """Example of making an authenticated API request."""
    try:
        response = requests.get(
            f"{auth_manager.base_url}/auth/verify",
            headers=auth_manager.get_auth_header(),
            timeout=10,
        )

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 401:
            # Token expired or invalid — user needs to log in again.
            return None
    except requests.exceptions.RequestException:
        return None

If the server responds with a 401 Unauthorized, that means the token has expired or been revoked. You should handle this gracefully — for example, by showing the login dialog again.

Handling Token Expiration

Tokens expire. When they do, your app needs to respond appropriately rather than silently failing. A common approach is to wrap your API calls in a method that checks for 401 responses and triggers a re-login:

python

def authenticated_request(auth_manager, method, url, **kwargs):
    """
    Make an HTTP request with authentication.
    Returns the response, or None if re-authentication fails.
    """
    kwargs.setdefault("headers", {})
    kwargs["headers"].update(auth_manager.get_auth_header())
    kwargs.setdefault("timeout", 10)

    try:
        response = requests.request(method, url, **kwargs)

        if response.status_code == 401:
            # Token expired — try to re-authenticate.
            if attempt_login(auth_manager):
                kwargs["headers"].update(
                    auth_manager.get_auth_header()
                )
                response = requests.request(method, url, **kwargs)
            else:
                return None

        return response

    except requests.exceptions.RequestException:
        return None

This function automatically retries the request with a new token if the first attempt gets a 401. The user sees the login dialog, re-enters their credentials, and the request proceeds as if nothing happened.

To try it out:

Start the auth server in one terminal: python auth_server.py
Run the client application in another terminal: python app.py
Log in as admin / admin123 to see full access, or viewer / viewer123 to see restricted access.

Try logging in with the wrong password — the dialog stays open and shows an error. Close the dialog without logging in and the app exits cleanly.

Security Considerations

A few things to keep in mind when implementing auth in a desktop application:

Never store passwords in the client. Your app should only ever send credentials to the server and receive a token back. The token is what you store (in memory, or securely on disk if you want "remember me" functionality).

Use HTTPS in production. Our example uses plain HTTP because it's running locally. In a real deployment, all communication between the client and server should be encrypted with TLS. The requests library handles HTTPS transparently — just change the URL to https://.

Tokens are temporary. JWTs (and most authentication tokens) have an expiration time. Design your app to handle expired tokens gracefully, as shown in the token expiration section above.

Client-side checks are not enough. Disabling a button in the UI doesn't prevent a technically savvy user from calling the underlying function. Any action that matters should be validated on the server side too. The client-side restrictions are a UX convenience, not a security boundary.

Store tokens securely. If you implement a "remember me" feature that persists the token between sessions, use your platform's secure storage — keyring is a good cross-platform Python library for this. Don't write tokens to plain text files. You can also use QSettings to persist non-sensitive user preferences like the last-used username, but avoid storing tokens or credentials there since QSettings does not provide encryption.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Fixing Missing Icons in PyInstaller-Packaged PyQt6 Applications on Windows — Why your app icon disappears after packaging and how to fix it

2026-05-27T06:00:00+00:00

I've packaged my PyQt application with PyInstaller, but the icon isn't showing up — both the executable icon and the running application icon are just the default Python/Windows icon. What's going on?

This is a common issue when packaging PyQt6 apps with PyInstaller on Windows. The good news is that it usually comes down to one of two straightforward causes: Windows icon caching, and missing resource files in your packaged output.

Setting the executable icon with PyInstaller

When you run PyInstaller, you can set the icon for the .exe file itself using the --icon flag:

pyinstaller --windowed --icon=myicon.ico myapp.py

This embeds the icon into the executable, so it shows up in File Explorer and on the desktop. The icon file needs to be in .ico format — .png or .svg won't work here.

After building, check the dist/ folder. Your .exe should display the custom icon. But sometimes... it doesn't.

Windows icon caching

Windows caches icons aggressively. If you've previously built your app without a custom icon, Windows may continue to show the old default icon even after you've rebuilt the app with the correct one.

This still catches me out, even though I know this. You'll reflexively start checking the config assuming something is wrong, and think you're going mad.

There are a few ways to deal with this:

Rename the executable. Changing the filename forces Windows to look up the icon fresh. This is the quickest way to confirm that your icon is actually embedded correctly.
Clear the Windows icon cache. You can do this by restarting Windows Explorer or by deleting the icon cache files manually. To manually clear the Windows icon cache open a Command Prompt and run:

python

ie4uinit.exe -show

After clearing the cache, the correct icon should appear.

You can also try turning your computer off and on again, or rather restarting Windows. That will also trigger the icon cache to rebuild.

Missing icon file at runtime

Setting the executable icon with --icon only affects what shows up in File Explorer. If your application also sets a window icon in code (using setWindowIcon), that icon file needs to be available at runtime too.

For example, if your code does this:

python

from PyQt6.QtWidgets import QApplication, QMainWindow
from PyQt6.QtGui import QIcon
import sys


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My Application")


app = QApplication(sys.argv)
app.setWindowIcon(QIcon("myicon.ico"))

window = MainWindow()
window.show()

app.exec()

Then myicon.ico needs to exist in the working directory when the packaged app runs. By default, PyInstaller doesn't include data files like .ico images unless you tell it to.

You can add the icon file to your build using the --add-data flag:

pyinstaller --windowed --icon=myicon.ico --add-data "myicon.ico;." myapp.py

On Linux or macOS, use : instead of ; as the separator:

pyinstaller --windowed --icon=myicon.ico --add-data "myicon.ico:." myapp.py

This copies myicon.ico into the output directory alongside your executable (or into the temporary directory if you're using --onefile).

An alternative approach (not available on PyQt6) is to use the Qt Resource System to embed your icon directly into your application, which avoids the need to bundle separate icon files entirely.

Handling `--onefile` builds

When you use --onefile, PyInstaller extracts everything to a temporary folder at runtime. Your code needs to know how to find files relative to that temporary folder. You can handle this by detecting the base path:

python

import sys
import os

if getattr(sys, 'frozen', False):
    # Running as a PyInstaller bundle
    basedir = sys._MEIPASS
else:
    # Running as a normal script
    basedir = os.path.dirname(__file__)

Then use basedir when constructing file paths:

python

app.setWindowIcon(QIcon(os.path.join(basedir, "myicon.ico")))

Taskbar grouping with an Application User Model ID

On Windows, the taskbar groups windows by their application identity. Without an explicit identity, Windows guesses — and sometimes guesses wrong. This can cause your app to show the Python icon in the taskbar, or to group instances inconsistently depending on where they were launched from.

You can fix this by setting an Application User Model ID before creating your QApplication. This tells Windows exactly which application this is:

python

import ctypes

myappid = "com.mycompany.myapp.1.0"
ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(myappid)

The string can be anything, but it's conventional to use a reverse-domain format. The value just needs to be unique to your application.

With an explicit app ID set, all instances of your app will group together in the taskbar regardless of where they were launched from — whether that's your IDE, the dist/ folder, or a --onefile build.

Complete working example

Here's a complete example that handles all of the above — the runtime base path, the window icon, and the application user model ID. If you're new to building PyQt6 applications, you may want to start with creating your first window before tackling packaging.

python

import sys
import os
import ctypes

from PyQt6.QtWidgets import QApplication, QMainWindow, QLabel
from PyQt6.QtGui import QIcon
from PyQt6.QtCore import Qt


# Set the app user model ID before creating QApplication (Windows only)
if sys.platform == "win32":
    myappid = "com.mycompany.myapp.1.0"
    ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(myappid)

# Determine the base directory for resource files
if getattr(sys, "frozen", False):
    basedir = sys._MEIPASS
else:
    basedir = os.path.dirname(__file__)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My Application")
        label = QLabel("Hello, world!")
        label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setCentralWidget(label)


app = QApplication(sys.argv)
app.setWindowIcon(QIcon(os.path.join(basedir, "myicon.ico")))

window = MainWindow()
window.show()

app.exec()

To package this with PyInstaller:

pyinstaller --windowed --icon=myicon.ico --add-data "myicon.ico;." myapp.py

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Adding QComboBox to a QTableView and getting/setting values after creation — Use QItemDelegate to embed combo boxes in your table views, with per-row data and value tracking

2026-05-20T06:00:00+00:00

I'm using a QTableView to display data, and would like to limit the choices in some of the fields using a drop-down. I can use QComboBox to provide a list of choices in a normal UI, but how can I do that in a table view?

When you're working with QTableView in PyQt6, you'll sometimes want cells that offer a dropdown selection instead of plain text. A QComboBox is the natural fit here — but embedding one inside a table view takes a bit of wiring up.

In this tutorial, we'll walk through how to use a QItemDelegate to place a QComboBox into specific cells of a QTableView. We'll also cover how to populate each combo box with different items per row, and how to retrieve the selected value so you can use it elsewhere in your application.

How delegates work in Qt's Model/View framework

Qt's Model/View architecture separates your data (the model) from how it's displayed (the view). Between these two sits the delegate, which controls how individual cells are rendered and edited. When you want a cell to use a widget like a combo box instead of a plain text editor, you create a custom delegate.

The delegate has a few methods you'll override:

createEditor() — creates the widget (in our case, a QComboBox) when the user starts editing a cell.
setEditorData() — populates the editor widget with the current data from the model.
setModelData() — writes the user's selection back into the model.
updateEditorGeometry() — makes sure the widget is sized and positioned correctly inside the cell.

Let's build this up step by step.

Setting up the model and view

First, let's create a simple application with a QTableView and a QStandardItemModel. Each row will represent a software package, and one of the columns will hold a list of available versions. We'll store those version lists directly in the model data, so each row can have its own set of options.

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QTableView, QComboBox, QItemDelegate,
)
from PyQt6.QtGui import QStandardItemModel, QStandardItem
from PyQt6.QtCore import Qt, QItemDataRole


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QComboBox in QTableView")

        self.table = QTableView()
        self.setCentralWidget(self.table)

        # Create a model with 3 rows and 2 columns.
        self.model = QStandardItemModel(3, 2)
        self.model.setHorizontalHeaderLabels(["Package", "Version"])

        # Each row has a package name and a list of available versions.
        packages = [
            ("Widget Library", ["1.0", "1.1", "2.0", "2.1"]),
            ("Data Toolkit", ["0.9", "1.0"]),
            ("Render Engine", ["3.0", "3.1", "3.2", "4.0"]),
        ]

        for row, (name, versions) in enumerate(packages):
            # Column 0: package name (plain text).
            self.model.setItem(row, 0, QStandardItem(name))

            # Column 1: store the version list in the item's data.
            # We use Qt.ItemDataRole.UserRole to keep the full list alongside the display text.
            item = QStandardItem(versions[-1])  # Display the latest version by default.
            item.setData(versions, Qt.ItemDataRole.UserRole)
            self.model.setItem(row, 1, item)

        self.table.setModel(self.model)

        # Apply our custom delegate to column 1.
        delegate = ComboDelegate(self.table)
        self.table.setItemDelegateForColumn(1, delegate)

        self.resize(400, 200)

Notice how we store the list of versions using Qt.ItemDataRole.UserRole. This is a custom data role — it lets us attach extra information to a model item without interfering with the text that's displayed (which uses Qt.ItemDataRole.DisplayRole). Each row gets its own version list, so when the combo box opens, it will show only the versions relevant to that row.

Creating the combo box delegate

Now let's write the ComboDelegate class. This is where the combo box gets created and connected to the model.

python

class ComboDelegate(QItemDelegate):
    """
    A delegate that places a QComboBox in cells of the assigned column.
    """

    def createEditor(self, parent, option, index):
        # Create the combo box and populate it with the version list for this row.
        combo = QComboBox(parent)
        versions = index.data(Qt.ItemDataRole.UserRole)
        if versions:
            combo.addItems(versions)
        return combo

    def setEditorData(self, editor, index):
        # Set the combo box to show the currently selected value.
        current_text = index.data(Qt.ItemDataRole.DisplayRole)
        idx = editor.findText(current_text)
        if idx >= 0:
            editor.setCurrentIndex(idx)

    def setModelData(self, editor, model, index):
        # Write the selected value back into the model.
        model.setData(index, editor.currentText(), Qt.ItemDataRole.DisplayRole)

    def updateEditorGeometry(self, editor, option, index):
        editor.setGeometry(option.rect)

Let's walk through each method:

createEditor() is called when the user double-clicks (or otherwise activates) a cell in column 1. We create a fresh QComboBox, pull the version list from Qt.ItemDataRole.UserRole for that specific row, and add those items to the combo box. Because each row stores its own list, different rows will show different options.

setEditorData() makes sure the combo box starts with the right item selected. We read the current display text from the model and find the matching entry in the combo box.

setModelData() fires when the user finishes editing (for example, by clicking away from the cell). It takes whatever the user selected in the combo box and writes it back into the model's DisplayRole.

updateEditorGeometry() simply ensures the combo box fills the cell neatly.

Running the application

Add the standard entry point at the bottom of your script:

python

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Run the script and double-click any cell in the "Version" column. You'll see a combo box appear with the version options for that specific row. Select a value, click away, and the cell updates.

Getting the selected value

After the user makes a selection, the value is stored in the model. You can read it at any time:

python

# Read the selected version for row 0.
selected = self.model.item(0, 1).text()
print(f"Row 0 selected version: {selected}")

If you want to react immediately when a selection changes, you can connect to the model's dataChanged signal. If you're new to how signals work in Qt, see our guide on signals, slots and events:

python

self.model.dataChanged.connect(self.on_data_changed)

def on_data_changed(self, top_left, bottom_right, roles):
    if top_left.column() == 1:
        row = top_left.row()
        value = top_left.data(Qt.ItemDataRole.DisplayRole)
        print(f"Row {row} version changed to: {value}")

This approach keeps things nicely separate — you're working through the model rather than trying to hold references to individual combo box widgets. The combo boxes are created and destroyed as the user interacts with cells.

Setting a value programmatically

To change a cell's value from code, update the model directly:

python

# Set row 2's version to "3.1".
self.model.item(2, 1).setText("3.1")

The next time the user opens the combo box on that row, the delegate's setEditorData() will position the combo box on "3.1".

You can also update the list of available versions for a row:

python

# Add a new version to row 1's options.
item = self.model.item(1, 1)
versions = item.data(Qt.ItemDataRole.UserRole)
versions.append("1.1")
item.setData(versions, Qt.ItemDataRole.UserRole)

Why each row gets its own combo box items

A common stumbling block is ending up with the same items in every combo box across the column. This happens when you store the item list on the delegate itself (as a single shared list) rather than on the model. Since the delegate is shared across all rows, any list stored on it will be the same everywhere.

The solution, as we've done here, is to store per-row data in the model using Qt.ItemDataRole.UserRole. Each call to createEditor() reads from the specific index it's given, so each row naturally gets its own set of options. This is a pattern you'll use often when different rows need different editor configurations.

Complete code

Here's the full working example in one block:

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QTableView, QComboBox, QItemDelegate,
)
from PyQt6.QtGui import QStandardItemModel, QStandardItem
from PyQt6.QtCore import Qt


class ComboDelegate(QItemDelegate):
    """
    A delegate that places a QComboBox in cells of the assigned column.
    """

    def createEditor(self, parent, option, index):
        combo = QComboBox(parent)
        versions = index.data(Qt.ItemDataRole.UserRole)
        if versions:
            combo.addItems(versions)
        return combo

    def setEditorData(self, editor, index):
        current_text = index.data(Qt.ItemDataRole.DisplayRole)
        idx = editor.findText(current_text)
        if idx >= 0:
            editor.setCurrentIndex(idx)

    def setModelData(self, editor, model, index):
        model.setData(index, editor.currentText(), Qt.ItemDataRole.DisplayRole)

    def updateEditorGeometry(self, editor, option, index):
        editor.setGeometry(option.rect)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QComboBox in QTableView")

        self.table = QTableView()
        self.setCentralWidget(self.table)

        self.model = QStandardItemModel(3, 2)
        self.model.setHorizontalHeaderLabels(["Package", "Version"])

        packages = [
            ("Widget Library", ["1.0", "1.1", "2.0", "2.1"]),
            ("Data Toolkit", ["0.9", "1.0"]),
            ("Render Engine", ["3.0", "3.1", "3.2", "4.0"]),
        ]

        for row, (name, versions) in enumerate(packages):
            self.model.setItem(row, 0, QStandardItem(name))
            item = QStandardItem(versions[-1])
            item.setData(versions, Qt.ItemDataRole.UserRole)
            self.model.setItem(row, 1, item)

        self.table.setModel(self.model)

        delegate = ComboDelegate(self.table)
        self.table.setItemDelegateForColumn(1, delegate)

        # React to changes.
        self.model.dataChanged.connect(self.on_data_changed)

        self.resize(400, 200)

    def on_data_changed(self, top_left, bottom_right, roles):
        if top_left.column() == 1:
            row = top_left.row()
            value = top_left.data(Qt.ItemDataRole.DisplayRole)
            print(f"Row {row} version changed to: {value}")


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Wrapping up

Using a custom QItemDelegate gives you full control over how cells in a QTableView are edited. By storing per-row data in the model with Qt.ItemDataRole.UserRole, you can give each combo box its own set of items — solving the common problem of all combo boxes showing the same options.

The pattern here — store data in the model, read it in the delegate, write changes back to the model — works well beyond combo boxes. You can use the same approach to embed spin boxes, date pickers, or any other widget into your table cells. Once you're comfortable with this flow, you'll find Qt's Model/View framework surprisingly flexible. For a deeper dive into using QTableView with real-world data sources like NumPy and Pandas, see our QTableView with numpy and pandas tutorial. You can also explore how to make table cells editable for other common editing patterns.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How to Add Custom Widgets to Qt Designer — Use widget promotion to integrate your own Python widgets into Qt Designer layouts

2026-05-13T06:00:00+00:00

Can I use custom widgets in Qt Designer?

When you're building Python GUI applications with PyQt6 and Qt Designer, you'll reach a point where the built-in widgets aren't enough. Maybe you've created a custom plotting widget or a specialized input control in Python, and you want to place it into your Qt Designer layouts alongside all the standard widgets.

The good news is that Qt Designer supports exactly this through a feature called widget promotion. In this tutorial, you'll learn how to take any custom Python widget and integrate it into your Qt Designer .ui files, so you can position and size it visually just like any built-in widget.

The bad news is that since Qt Designer is a C++ application, it can't run your Python code. That means you won't see your custom widget rendered in the Designer preview. Instead, you'll see a placeholder (the base widget type you promoted from). Once you load the .ui file in your running Python application, your custom widget appears in all its glory.

With that caveat aside, let's look at how we can use custom widgets in Qt Designer.

Widget promotion is Qt Designer's way of letting you swap a standard widget for a custom one. You start by placing a regular widget on your form, a plain QWidget for example, and then tell Qt Designer: "When this UI is actually used, replace this placeholder with my custom widget class instead."

Behind the scenes, this adds some extra information to the .ui file. When you load that file in Python using uic.loadUi() or compile it with pyuic6, the loader knows to import your custom class and use it in place of the base widget.

Before we get into Qt Designer, let's create a simple custom widget in Python. We'll make a basic colored widget that draws a gradient background—something you'd never get from a standard widget.

Create a new file called custom_widgets.py:

python

from PyQt6.QtWidgets import QWidget
from PyQt6.QtGui import QPainter, QLinearGradient, QColor
from PyQt6.QtCore import Qt


class GradientWidget(QWidget):
    """A custom widget that displays a gradient background."""

    def __init__(self, parent=None):
        super().__init__(parent)

    def paintEvent(self, event):
        painter = QPainter(self)
        gradient = QLinearGradient(0, 0, self.width(), self.height())
        gradient.setColorAt(0.0, QColor("#2c3e50"))
        gradient.setColorAt(1.0, QColor("#3498db"))
        painter.fillRect(self.rect(), gradient)
        painter.end()

This widget overrides paintEvent to draw a diagonal gradient from dark blue to lighter blue. It's a straightforward example, but the same promotion process works for any custom widget—complex plotting canvases, custom controls, or anything else you build by subclassing a Qt widget.

Setting Up Your Project Structure

For widget promotion to work, the Python file containing your custom widget needs to be importable when your application runs. The simplest way to achieve this is to keep everything in the same directory:

python

my_project/
├── custom_widgets.py      # Your custom widget classes
├── mainwindow.ui          # Your Qt Designer file
└── main.py                # Your application entry point

The file name and class name matter here—you'll need to tell Qt Designer both of these during the promotion step.

Now we can open Qt Designer and set up the promotion.

Place a base widget on your form

Open Qt Designer and create a new Main Window (or open your existing .ui file). From the widget box on the left, drag a plain Widget (QWidget) onto your form. Position and resize it however you like—this is where your custom widget will appear when the application runs.

You can use any base widget class as your starting point. If your custom widget subclasses QPushButton, promote a QPushButton. If it subclasses QLabel, promote a QLabel. For our GradientWidget, which subclasses QWidget, a plain QWidget is the right choice.

Open the Promote Widgets dialog

Right-click on the widget you just placed. In the context menu, select Promote to.... This opens the Promoted Widgets dialog.

Fill in the promotion details

In the dialog, you'll see fields for three pieces of information:

Base class name — This should already be filled in with the type of widget you right-clicked on (e.g., QWidget). Leave this as is.
Promoted class name — Enter the name of your custom Python class. For our example, type GradientWidget.
Header file — This is where Qt Designer's C++ heritage shows through. In C++, this would be a header file path. For Python, you enter the module import path for your widget, without the .py extension. Since our class lives in custom_widgets.py, type custom_widgets.

Leave the Global include checkbox unchecked.

Add and promote

Click Add to add your class to the list of known promoted widgets. Then, with your class selected in the list, click Promote. The dialog closes, and you'll notice the widget's class name in the Object Inspector (top-right panel) now shows GradientWidget instead of QWidget.

That's it for the Designer side. Save your .ui file.

Promoting additional widgets

Once you've added a promoted class through this dialog, it becomes available for reuse. The next time you want to promote a widget to GradientWidget, just right-click the widget and you'll see it listed directly in the Promote to submenu—no need to open the full dialog again.

Loading the UI in Python

Now let's write the Python code to load the .ui file and see our custom widget in action. Create main.py:

python

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow
from PyQt6 import uic


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        uic.loadUi("mainwindow.ui", self)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

When you run this, uic.loadUi() reads the .ui file and sees that one of the widgets has been promoted to GradientWidget from the custom_widgets module. It automatically does the equivalent of:

python

from custom_widgets import GradientWidget

...and creates an instance of GradientWidget wherever you placed that promoted widget in your layout. Instead of a blank QWidget, you'll see your gradient background.

Using Compiled UI Files

If you prefer to compile your .ui files to Python using pyuic6 rather than loading them at runtime, promotion works the same way. Run:

pyuic6 mainwindow.ui -o ui_mainwindow.py

If you open the generated ui_mainwindow.py, you'll find an import line near the bottom:

python

from custom_widgets import GradientWidget

The compiled code creates your GradientWidget instance in the right place automatically. You can then use the generated file in your application:

python

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow
from ui_mainwindow import Ui_MainWindow


class MainWindow(QMainWindow, Ui_MainWindow):
    def __init__(self):
        super().__init__()
        self.setupUi(self)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Both approaches—runtime loading and compiled files—handle promoted widgets in the same way.

A More Practical Example: Embedding PyQtGraph

One of the most common reasons to promote widgets is to embed third-party plotting libraries like PyQtGraph into your Designer layouts. PyQtGraph's PlotWidget is a subclass of QGraphicsView, so you'd promote a QGraphicsView in Designer.

Here's how you'd fill in the promotion dialog for PyQtGraph:

Base class name: QGraphicsView
Promoted class name: PlotWidget
Header file: pyqtgraph

That's all it takes. When your application runs, the placeholder QGraphicsView becomes a fully functional PlotWidget that you can plot data on.

python

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow
from PyQt6 import uic


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        uic.loadUi("mainwindow.ui", self)

        # self.graphWidget is the promoted PlotWidget
        # (use the objectName you set in Designer)
        self.graphWidget.plot([1, 2, 3, 4, 5], [10, 20, 15, 30, 25])


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Promoting Widgets from Submodules

If your custom widget lives in a submodule or package, you can use dotted import paths in the Header file field. For example, if your project structure looks like this:

python

my_project/
├── widgets/
│   ├── __init__.py
│   └── gradient.py    # contains GradientWidget
├── mainwindow.ui
└── main.py

You would enter widgets.gradient as the header file in the promotion dialog. The loader will then do:

python

from widgets.gradient import GradientWidget

This keeps things organized as your project grows.

Troubleshooting Common Issues

"No module named 'custom_widgets'" — This means Python can't find the file containing your custom widget class. Make sure the module file is in the same directory as your script (or somewhere on your Python path), and that the name in the promotion dialog matches the file name exactly (without .py).

The widget appears blank or as a plain QWidget — Double-check that the promoted class name matches your Python class name exactly, including capitalization. GradientWidget and gradientwidget are different classes as far as Python is concerned.

The widget doesn't resize properly — Make sure you've added the promoted widget to a layout in Qt Designer. Widgets outside of layouts won't resize with the window, regardless of whether they're promoted or not.

Changes to your custom widget don't appear in Designer — Remember, Qt Designer can't render Python widgets. You'll always see the base widget type in the Designer preview. Run your application to see your custom widget.

Summary

Widget promotion is a straightforward way to bridge the gap between Qt Designer's visual layout tools and your custom Python widgets. The process is always the same:

Place a base widget of the appropriate type in Qt Designer.
Right-click and promote it, specifying your custom class name and module path.
Save the .ui file and load it in your Python application.

Your custom widget won't be visible in the Designer preview—that's expected. But when your application runs, the promoted widget is swapped in seamlessly, giving you the best of both worlds: visual layout design with the full power of custom Python widgets.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Sorting and Filtering a QTableView with QSortFilterProxyModel — Learn how to add interactive sorting and filtering to your PyQt/PySide table views without touching your underlying data

2026-05-06T06:00:00+00:00

I'm using QTableView to show some data, which works well. But I would like to be able to sort the data by different columns. How can I do this without sorting the data manually?

If you've already built a QTableView with a custom model, you might be wondering how to let users sort columns by clicking headers or filter rows based on search input. The good news is that Qt provides a ready-made tool for this: QSortFilterProxyModel. It sits between your model and your view, rearranging and filtering the data without modifying the original source. Your data stays untouched — the proxy just changes how it's presented.

In this tutorial, we'll start with a simple table model and progressively add sorting, filtering, and then tackle some of the common pitfalls — like working with proxy indexes correctly and avoiding crashes when updating data.

A Simple Table Model

Let's begin with a basic QTableView displaying a list-of-lists. This is the same pattern used in the model/view architecture tutorial.

python

import sys
from PyQt6.QtCore import Qt, QAbstractTableModel
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data
        self._headers = ["Name", "Age", "City"]

    def data(self, index, role):
        if role == Qt.ItemDataRole.DisplayRole:
            return self._data[index.row()][index.column()]

    def rowCount(self, index):
        return len(self._data)

    def columnCount(self, index):
        return len(self._data[0])

    def headerData(self, section, orientation, role):
        if role == Qt.ItemDataRole.DisplayRole:
            if orientation == Qt.Orientation.Horizontal:
                return self._headers[section]


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.table = QTableView()

        data = [
            ["Alice", 25, "New York"],
            ["Bob", 30, "Denver"],
            ["Charlie", 35, "Austin"],
            ["Diana", 28, "Denver"],
            ["Eve", 22, "Austin"],
        ]

        self.model = TableModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)
        self.setWindowTitle("QTableView — No Sorting Yet")
        self.resize(500, 300)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Run this and you'll see a plain table. Clicking the column headers does nothing as sorting is off by default. Let's change that first.

Adding sorting with QSortFilterProxyModel

To add sorting, we insert a QSortFilterProxyModel between our TableModel and the QTableView. The proxy model wraps the source model and provides sorted (and later, filtered) access to the same data.

Here's what changes in the MainWindow.__init__ method:

python

from PyQt6.QtCore import Qt, QAbstractTableModel, QSortFilterProxyModel

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.table = QTableView()

        data = [
            ["Alice", 25, "New York"],
            ["Bob", 30, "Denver"],
            ["Charlie", 35, "Austin"],
            ["Diana", 28, "Denver"],
            ["Eve", 22, "Austin"],
        ]

        self.model = TableModel(data)

        self.proxy_model = QSortFilterProxyModel()
        self.proxy_model.setSourceModel(self.model)

        self.table.setModel(self.proxy_model)
        self.table.setSortingEnabled(True)

        self.setCentralWidget(self.table)
        self.setWindowTitle("QTableView — Sortable!")
        self.resize(500, 300)

We've added the following steps:

Create the QSortFilterProxyModel.
Tell it which source model to wrap with setSourceModel().
Give the proxy model to the view (not the source model), and call setSortingEnabled(True) on the view.

Now when you click a column header, the rows reorder. Click again to reverse the sort direction. The little arrow indicator on the header shows you which column is currently sorted and in which direction.

Notice that the underlying data list hasn't changed at all. The proxy model handles everything by remapping indexes.

Adding filtering

Filtering works through the same proxy model. You tell the proxy which column to look at and what pattern to match, and it hides rows that don't match.

Let's add a QLineEdit that filters rows as you type. We'll filter on the "City" column (column index 2). If you're interested in a more complete search bar implementation, see the widget search bar tutorial.

python

import sys
from PyQt6.QtCore import Qt, QAbstractTableModel, QSortFilterProxyModel
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QTableView,
    QVBoxLayout, QWidget, QLineEdit, QLabel,
)


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data
        self._headers = ["Name", "Age", "City"]

    def data(self, index, role):
        if role == Qt.ItemDataRole.DisplayRole:
            return self._data[index.row()][index.column()]

    def rowCount(self, index):
        return len(self._data)

    def columnCount(self, index):
        return len(self._data[0])

    def headerData(self, section, orientation, role):
        if role == Qt.ItemDataRole.DisplayRole:
            if orientation == Qt.Orientation.Horizontal:
                return self._headers[section]


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        data = [
            ["Alice", 25, "New York"],
            ["Bob", 30, "Denver"],
            ["Charlie", 35, "Austin"],
            ["Diana", 28, "Denver"],
            ["Eve", 22, "Austin"],
        ]

        self.model = TableModel(data)

        self.proxy_model = QSortFilterProxyModel()
        self.proxy_model.setSourceModel(self.model)
        self.proxy_model.setFilterCaseSensitivity(
            Qt.CaseSensitivity.CaseInsensitive
        )
        self.proxy_model.setFilterKeyColumn(2)  # Filter on "City" column

        self.table = QTableView()
        self.table.setModel(self.proxy_model)
        self.table.setSortingEnabled(True)

        self.search_input = QLineEdit()
        self.search_input.setPlaceholderText("Filter by city...")
        self.search_input.textChanged.connect(
            self.proxy_model.setFilterFixedString
        )

        layout = QVBoxLayout()
        layout.addWidget(QLabel("Search:"))
        layout.addWidget(self.search_input)
        layout.addWidget(self.table)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)
        self.setWindowTitle("QTableView — Sort & Filter")
        self.resize(500, 400)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Type "Denver" into the search box and the table instantly filters to show only the rows where the City column matches. Type "aus" and you'll see the Austin rows (because we set case-insensitive matching).

Let's recap what's happening:

setFilterKeyColumn(2) tells the proxy to check column 2 ("City") when deciding which rows to show.
setFilterFixedString performs a plain substring match. If the filter string appears anywhere in the cell value, the row is shown.
We connected the textChanged signal from the QLineEdit directly to setFilterFixedString on the proxy model. Every time the user types, the filter updates automatically.

Filtering across all columns

If you want to search across every column instead of just one, set the filter key column to -1:

python

self.proxy_model.setFilterKeyColumn(-1)  # Search all columns

Now typing "25" will match Alice's row (age 25), and typing "Den" will still match the Denver rows.

Other filter modes

setFilterFixedString is the simplest option — it does a plain text substring match. The proxy model also supports more powerful matching:

Wildcard matching using setFilterWildcard() — supports * and ? patterns, like "D*ver".
Regular expression matching using setFilterRegularExpression() — supports full regex patterns for complex matching needs.

For most interactive search boxes, setFilterFixedString with case-insensitive matching is exactly what you need.

Working with proxy indexes correctly

When a proxy model is active, the indexes your view reports are proxy indexes, not source model indexes. If you click on a row in the filtered/sorted view, the QModelIndex you receive refers to the proxy model's row numbering, which may not match the original data.

This matters when you need to do something with the underlying data — like reading values from the source model or modifying a specific row.

Consider this slot connected to the table's clicked signal:

python

self.table.clicked.connect(self.cell_clicked)

def cell_clicked(self, proxy_index):
    # This gives the row number in the proxy (filtered/sorted) view
    print(f"Proxy row: {proxy_index.row()}, column: {proxy_index.column()}")

    # To get the corresponding row in the SOURCE model:
    source_index = self.proxy_model.mapToSource(proxy_index)
    print(f"Source row: {source_index.row()}, column: {source_index.column()}")

The method mapToSource() translates a proxy index back to the source model's coordinate system. There's also mapFromSource() for going the other direction — converting a source index into the proxy's index, which is useful if you need to select or highlight a specific row in the view programmatically.

If you forget this step and pass proxy indexes directly to your source model, you'll end up reading or modifying the wrong row. When filtering is active, the mismatch becomes obvious because the proxy's row 0 might correspond to row 3 in the source.

Reading data through the proxy

When you want to read data from a clicked row, you have two options:

python

def cell_clicked(self, proxy_index):
    row = proxy_index.row()

    # Option 1: Read through the proxy model (uses proxy indexes)
    name = self.proxy_model.data(
        self.proxy_model.index(row, 0),
        Qt.ItemDataRole.DisplayRole,
    )

    # Option 2: Map to source and read from source model
    source_index = self.proxy_model.mapToSource(proxy_index)
    name = self.model.data(
        self.model.index(source_index.row(), 0),
        Qt.ItemDataRole.DisplayRole,
    )

    print(f"Clicked on: {name}")

Both options give you the same result. Option 1 is often simpler since you're already working with proxy indexes from the view. Option 2 is necessary when you need to interact directly with the source model — for example, to modify data or get the "real" row position in your data structure.

Avoiding crashes when updating the source model

If you're updating the source model's data while a proxy model and view are connected, you need to properly notify Qt's model/view framework about the changes. Without these notifications, you can get segmentation faults or corrupted displays.

The pattern for updating data looks like this inside your QAbstractTableModel subclass:

python

def update_data(self, new_data):
    self.layoutAboutToBeChanged.emit()
    self._data = new_data
    self.layoutChanged.emit()

The layoutAboutToBeChanged signal tells the proxy model (and the view) that the structure of the data is about to change. After you've made your changes, layoutChanged tells everything to refresh. Skipping the layoutAboutToBeChanged signal is a common cause of crashes — the proxy model needs that heads-up to properly invalidate its internal mapping of indexes.

For smaller changes, like updating a single cell, you can use dataChanged instead:

python

def set_value(self, row, col, value):
    self._data[row][col] = value
    index = self.index(row, col)
    self.dataChanged.emit(index, index)

And if you're adding or removing rows, use beginInsertRows/endInsertRows or beginRemoveRows/endRemoveRows:

python

def add_row(self, row_data):
    row_position = len(self._data)
    self.beginInsertRows(self.index(row_position, 0).parent(), row_position, row_position)
    self._data.append(row_data)
    self.endInsertRows()

Getting these signals right is what keeps the proxy model, the view, and your data all in sync.

Custom sorting behavior

The default sorting provided by QSortFilterProxyModel uses Qt.ItemDataRole.DisplayRole and works well for simple string and number comparisons. But sometimes you need more control — for example, sorting a column of dates that are stored as strings, or sorting with a custom priority order.

To customize sorting, subclass QSortFilterProxyModel and override the lessThan method. This method receives two QModelIndex objects (from the source model) and should return True if the left value should come before the right value.

python

class CustomProxyModel(QSortFilterProxyModel):
    def lessThan(self, left, right):
        left_data = self.sourceModel().data(left, Qt.ItemDataRole.DisplayRole)
        right_data = self.sourceModel().data(right, Qt.ItemDataRole.DisplayRole)

        # Example: sort numerically if both values are numbers
        try:
            return float(left_data) < float(right_data)
        except (ValueError, TypeError):
            # Fall back to string comparison
            return str(left_data).lower() < str(right_data).lower()

Then use CustomProxyModel instead of QSortFilterProxyModel:

python

self.proxy_model = CustomProxyModel()
self.proxy_model.setSourceModel(self.model)

This is useful when your table has mixed data types or when the display representation doesn't sort the way you'd expect (like date strings in "MM/DD/YYYY" format).

Custom filtering behavior

Similarly, you can customize filtering by subclassing QSortFilterProxyModel and overriding filterAcceptsRow. This method is called for every row in the source model, and it should return True if the row should be visible.

Here's an example that filters to show only rows where the "Age" column (column 1) is above a certain threshold:

python

class AgeFilterProxyModel(QSortFilterProxyModel):
    def __init__(self):
        super().__init__()
        self._min_age = 0

    def set_min_age(self, age):
        self._min_age = age
        self.invalidateFilter()  # Re-apply the filter

    def filterAcceptsRow(self, source_row, source_parent):
        index = self.sourceModel().index(source_row, 1, source_parent)
        age = self.sourceModel().data(index, Qt.ItemDataRole.DisplayRole)
        try:
            return int(age) >= self._min_age
        except (ValueError, TypeError):
            return True

After changing your filter criteria, call invalidateFilter() to tell the proxy model to re-evaluate which rows should be shown.

You can combine this with the text-based column filtering too. If you override filterAcceptsRow, you have full control — you can check multiple columns, apply complex logic, or combine several filter conditions:

python

def filterAcceptsRow(self, source_row, source_parent):
    model = self.sourceModel()

    # Check age filter
    age_index = model.index(source_row, 1, source_parent)
    age = model.data(age_index, Qt.ItemDataRole.DisplayRole)
    if int(age) < self._min_age:
        return False

    # Check text filter on city column
    city_index = model.index(source_row, 2, source_parent)
    city = model.data(city_index, Qt.ItemDataRole.DisplayRole)
    if self.filterRegularExpression().pattern():
        if not self.filterRegularExpression().match(city).hasMatch():
            return False

    return True

Putting it all together

Here's a complete example that combines sorting, text filtering, and a numeric age filter using a custom proxy model:

python

import sys
from PyQt6.QtCore import Qt, QAbstractTableModel, QSortFilterProxyModel
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QTableView,
    QVBoxLayout, QHBoxLayout, QWidget,
    QLineEdit, QLabel, QSpinBox,
)


class TableModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data
        self._headers = ["Name", "Age", "City"]

    def data(self, index, role):
        if role == Qt.ItemDataRole.DisplayRole:
            return self._data[index.row()][index.column()]

    def rowCount(self, index):
        return len(self._data)

    def columnCount(self, index):
        return len(self._data[0])

    def headerData(self, section, orientation, role):
        if role == Qt.ItemDataRole.DisplayRole:
            if orientation == Qt.Orientation.Horizontal:
                return self._headers[section]


class CustomFilterProxyModel(QSortFilterProxyModel):
    def __init__(self):
        super().__init__()
        self._min_age = 0
        self._city_filter = ""

    def set_min_age(self, age):
        self._min_age = age
        self.invalidateFilter()

    def set_city_filter(self, text):
        self._city_filter = text.lower()
        self.invalidateFilter()

    def filterAcceptsRow(self, source_row, source_parent):
        model = self.sourceModel()

        # Age filter (column 1)
        age_index = model.index(source_row, 1, source_parent)
        age = model.data(age_index, Qt.ItemDataRole.DisplayRole)
        try:
            if int(age) < self._min_age:
                return False
        except (ValueError, TypeError):
            pass

        # City text filter (column 2)
        if self._city_filter:
            city_index = model.index(source_row, 2, source_parent)
            city = model.data(city_index, Qt.ItemDataRole.DisplayRole)
            if self._city_filter not in str(city).lower():
                return False

        return True


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        data = [
            ["Alice", 25, "New York"],
            ["Bob", 30, "Denver"],
            ["Charlie", 35, "Austin"],
            ["Diana", 28, "Denver"],
            ["Eve", 22, "Austin"],
            ["Frank", 40, "New York"],
            ["Grace", 19, "Denver"],
        ]

        self.model = TableModel(data)

        self.proxy_model = CustomFilterProxyModel()
        self.proxy_model.setSourceModel(self.model)

        self.table = QTableView()
        self.table.setModel(self.proxy_model)
        self.table.setSortingEnabled(True)
        self.table.clicked.connect(self.cell_clicked)

        # City filter
        self.city_input = QLineEdit()
        self.city_input.setPlaceholderText("Filter by city...")
        self.city_input.textChanged.connect(self.proxy_model.set_city_filter)

        # Age filter
        self.age_spin = QSpinBox()
        self.age_spin.setRange(0, 100)
        self.age_spin.setPrefix("Min age: ")
        self.age_spin.valueChanged.connect(self.proxy_model.set_min_age)

        filter_layout = QHBoxLayout()
        filter_layout.addWidget(QLabel("City:"))
        filter_layout.addWidget(self.city_input)
        filter_layout.addWidget(self.age_spin)

        layout = QVBoxLayout()
        layout.addLayout(filter_layout)
        layout.addWidget(self.table)

        self.status_label = QLabel("Click a row to see details")
        layout.addWidget(self.status_label)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)
        self.setWindowTitle("QTableView — Sort & Custom Filter")
        self.resize(500, 400)

    def cell_clicked(self, proxy_index):
        source_index = self.proxy_model.mapToSource(proxy_index)
        row = proxy_index.row()
        name = self.proxy_model.data(
            self.proxy_model.index(row, 0),
            Qt.ItemDataRole.DisplayRole,
        )
        age = self.proxy_model.data(
            self.proxy_model.index(row, 1),
            Qt.ItemDataRole.DisplayRole,
        )
        city = self.proxy_model.data(
            self.proxy_model.index(row, 2),
            Qt.ItemDataRole.DisplayRole,
        )
        self.status_label.setText(
            f"Selected: {name}, age {age}, from {city} "
            f"(source row: {source_index.row()})"
        )


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Try playing with this example:

Click column headers to sort by name, age, or city.
Type in the city filter to narrow down results.
Adjust the minimum age spinner to hide younger entries.
Click on rows and notice how the source row number differs from the visible row number.

Summary

Here's a quick recap of everything we covered:

QSortFilterProxyModel sits between your model and your view. It sorts and filters data without modifying the source.
Call setSortingEnabled(True) on the view to let users sort by clicking column headers.
Use setFilterKeyColumn() and setFilterFixedString() for quick text filtering. Set the column to -1 to search all columns.
Always use mapToSource() when you need to convert a proxy index back to the source model's coordinate system.
Emit layoutAboutToBeChanged and layoutChanged when replacing data in the source model to avoid crashes.
Subclass QSortFilterProxyModel and override lessThan() for custom sorting or filterAcceptsRow() for custom filtering.
Call invalidateFilter() after changing filter criteria in a custom proxy model.

The proxy model pattern is one of the most powerful parts of Qt's model/view architecture. Once you have it set up, you get flexible data presentation without ever duplicating or restructuring your underlying data. To explore model/view further, see how to display numpy and pandas data in a QTableView or learn about signals, slots, and events that power these interactions.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Streamlit Buttons — Making things happen with Streamlit buttons

2026-05-01T06:00:00+00:00

Streamlit is a popular choice for creating interactive web applications in Python. With its simple syntax and intuitive interface, developers can quickly create visually appealing dashboards.

One of the great things about Streamlit is its ability to easily handle user interaction, and dynamically update the UI in response. One of the main way for users to trigger actions in UIs is through the use of buttons. In Streamlit, the st.button() method creates a button that users can click to perform an action. Each button can be associated with a different action.

In this tutorial we'll look at how you can use buttons to add interactivity to your Streamlit apps.

Creating Buttons in Streamlit

To create a button in Streamlit, you use the st.button() function, which takes an optional label as an argument. When the button is clicked, it returns True, which you can use to control subsequent actions.

Basic Button Syntax

Here's a simple example of a button in Streamlit:

python

import streamlit as st

if st.button('Click Me'):
    st.write("Button clicked!")

Simple Streamlit app with a single button

The st.button('Click Me') creates a button labeled Click Me. When the button is clicked, it returns True and the if evaluates to true running the nested code underneath -- displaying the message "Button clicked!"

This basic structure is the foundation of working with buttons in Streamlit. Through this simple mechanism you can build quite complex interactivity.

Multiple Buttons for Different Actions

Building on the basic button structure, you can create multiple buttons within your Streamlit app, each associated with different actions. For instance, let's create buttons that display different messages based on which is clicked.

python

import streamlit as st

if st.button('Show Greeting'):
    st.write("Hello, welcome to the app!")

if st.button('Show Goodbye'):
    st.write("Goodbye! See you soon.")

Simple Streamlit app with two buttons

Each button is wrapped in a conditional statement. When a button is pressed, the corresponding action is executed. Depending on the button pressed, different messages are displayed, providing immediate feedback to the user.

This structure is versatile and can be expanded to include more buttons and actions.

Displaying Dynamic Content Based on Button Clicks

Buttons can be used to display all types of content dynamically, including text, images, and charts. For example, below is a similar example but displaying images.

python

import streamlit as st

img_url_1 = "https://placehold.co/150/FF0000"
img_url_2 = "https://placehold.co/150/8ACE00"

if st.button('Show Red Image'):
    st.image(img_url_1, caption="This is a red image")

if st.button('Show Green Image'):
    st.image(img_url_2, caption="This is a green image")

Simple Streamlit app with two buttons showing images

When the Show Red Image button is pressed, a red image is displayed. The same goes for the Show Green Image button. This setup allows users to switch between different images based on their preferences.

Note that the state isn't persisted between each interaction. When you click on the "Show Red Image" the green image will disappear, and vice versa. This isn't a toggle but a natural consequence of how Streamlit works: the code of the script is executed on each interaction, so only one button can be in a "clicked" state at any time.

To persist state between runs of the script, you can use Streamlit's state management features. We'll cover this in a future tutorial.

Dynamic Forms Based on Button Press

Dynamic forms allow users to provide input in a structured way, which can vary based on user actions. This is particularly useful for collecting information without overwhelming users with multiple fields.

Here's a quick example where users can input their name and age based on button presses:

python

import streamlit as st

# Title
st.title("Dynamic Forms Based on Button Press")

# Name Input Field
if st.button('Enter Name'):
    name = st.text_input('What is your name?')
    if name:
        st.write(f"Hello, {name}\!")

# Age Input Field

if st.button('Enter Age'):
    age = st.number_input('What is your age?', min_value=1, max_value=120)
    if age:
        st.write(f"Your age is {age}.")

The button Enter Name triggers a text input field when clicked, allowing users to enter their names. The button Enter Age displays a number input field for users to enter their age. The app provides immediate feedback based on user input.

Handling Form Submission

For more complex collections of inputs that you want to work together, consider using st.form() to group inputs, allowing users to submit all inputs at once:

python

import streamlit as st

# Title
st.title("Dynamic Forms Based on Button Press")

with st.form("my_form"):
    name = st.text_input('What is your name?')
    age = st.number_input('What is your age?', min_value=1, max_value=120)
    submitted = st.form_submit_button("Submit")

    if submitted:
        st.write(f"Hello, {name}\! Your age is {age}.")

Streamlit form with submit button

Conclusion

In this tutorial, we explored how to make things happen in Streamlit using buttons. We learned how to create multiple buttons and display dynamic content based on user interaction.

Now that you have a basic understanding of buttons in Streamlit, you can add basic interaction to your Streamlit applications.

Actions in one thread changing data in another — How to communicate between threads and windows in PyQt6

2026-04-29T06:00:00+00:00

I have a main window that starts background threads (e.g., handling GPIO data). From the main window I open secondary windows using buttons. When I press a button in a secondary window, I can't change anything in the background threads. But if I press a button in the main window, everything works. How do I communicate between a secondary window and a thread that was started from the main window?

This is a common problem when building PyQt6 applications with multiple windows and background threads. The good news is that Qt's signal and slot system is designed to handle this and it works safely across threads.

The core idea is that your secondary window doesn't need direct access to the thread or the worker object. Instead the secondary window and the worker just need access to the same signals, and can then use them to communicate with one another. Qt handles the cross-thread communication automatically.

Why doesn't direct access work?

When you create a background thread from the main window, you'll often store a reference to that thread on the main window. If that main window then creates a sub-window, it doesn't have any access to the objects on it's parent. Even if it did calling the methods on the thread directly is not usually the right approach.

You can access the attributes of a parent window using .parent() but this is a bad habit, because it tightly couples the parts of your application together. If you modify the structure of the parent window, you now need to also edit the sub-window. There are better ways that keep things nicely isolated.

The solution is to avoid calling methods directly across threads. Instead, use signals and slots. When a signal is emitted in one thread and connected to a slot in another, Qt automatically queues the call and delivers it safely.

Setting up a background worker

First, let's create a simple worker class that runs in a background thread. This worker simulates handling incoming data (like GPIO data) and also accepts commands from the GUI.

python

from PyQt6.QtCore import QObject, pyqtSignal, pyqtSlot
import time


class Worker(QObject):
    """A worker that runs in a background thread."""
    data_updated = pyqtSignal(str)

    def __init__(self):
        super().__init__()
        self.running = True
        self.current_value = 0

    @pyqtSlot()
    def run(self):
        """Simulate continuous data handling."""
        while self.running:
            self.current_value += 1
            self.data_updated.emit(f"Data: {self.current_value}")
            time.sleep(1)

    @pyqtSlot(int)
    def set_value(self, value):
        """Receive a new value from the GUI."""
        self.current_value = value
        self.data_updated.emit(f"Value set to: {self.current_value}")

The set_value slot is what we'll trigger from the secondary window. Because it's a slot connected via a signal, Qt will deliver the call on the correct thread.

Creating the secondary window

The secondary window has a button and a spin box. When the user clicks the button, the window emits a signal carrying the new value. The secondary window doesn't know anything about the worker — it just emits a signal.

python

from PyQt6.QtWidgets import QWidget, QVBoxLayout, QPushButton, QSpinBox, QLabel
from PyQt6.QtCore import pyqtSignal


class SecondaryWindow(QWidget):
    """A secondary window that emits a signal when the user sets a value."""
    value_changed = pyqtSignal(int)

    def __init__(self):
        super().__init__()
        self.setWindowTitle("Secondary Window")

        layout = QVBoxLayout()

        self.label = QLabel("Set a new value for the worker:")
        layout.addWidget(self.label)

        self.spinbox = QSpinBox()
        self.spinbox.setRange(0, 1000)
        layout.addWidget(self.spinbox)

        self.button = QPushButton("Send to Worker")
        self.button.clicked.connect(self.send_value)
        layout.addWidget(self.button)

        self.setLayout(layout)

    def send_value(self):
        self.value_changed.emit(self.spinbox.value())

The value_changed signal is the only interface this window exposes. This keeps things clean and decoupled.

Wiring everything together in the main window

The main window is where all the connections happen. It creates the worker, starts the thread, opens the secondary window, and connects the secondary window's signal to the worker's slot.

python

from PyQt6.QtWidgets import QMainWindow, QVBoxLayout, QPushButton, QLabel, QWidget
from PyQt6.QtCore import QThread


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Main Window")

        # Set up the UI
        layout = QVBoxLayout()

        self.status_label = QLabel("Waiting for data...")
        layout.addWidget(self.status_label)

        self.open_button = QPushButton("Open Secondary Window")
        self.open_button.clicked.connect(self.open_secondary)
        layout.addWidget(self.open_button)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

        # Keep a reference to the secondary window
        self.secondary_window = None

        # Set up the background thread and worker
        self.thread = QThread()
        self.worker = Worker()
        self.worker.moveToThread(self.thread)

        # Connect signals
        self.thread.started.connect(self.worker.run)
        self.worker.data_updated.connect(self.update_status)

        # Start the thread
        self.thread.start()

    def update_status(self, text):
        self.status_label.setText(text)

    def open_secondary(self):
        if self.secondary_window is None:
            self.secondary_window = SecondaryWindow()

            # Connect the secondary window's signal to the worker's slot.
            # This is the connection that makes cross-window,
            # cross-thread communication work.
            self.secondary_window.value_changed.connect(self.worker.set_value)

        self.secondary_window.show()

    def closeEvent(self, event):
        self.worker.running = False
        self.thread.quit()
        self.thread.wait()
        super().closeEvent(event)

The line that connects everything together is:

python

self.secondary_window.value_changed.connect(self.worker.set_value)

This connects a signal from the secondary window (running in the main/GUI thread) to a slot on the worker (which has been moved to a background thread). Qt sees that the sender and receiver live in different threads, so it automatically uses a queued connection. The slot call is placed into the background thread's event queue and executed there.

Understanding why the main window worked but the secondary didn't

In the original question, buttons in the main window could affect the background threads, but buttons in a secondary window could not. This usually happens because:

The main window had direct signal-slot connections to the worker (set up when both the worker and the connections were created).
The secondary window was created later, and its signals were never connected to the worker.

To solution is to connect its signals to the appropriate worker slots, when you create the secondary window, just as you would for the main window. The worker doesn't care where the signal comes from — it just responds to whatever signals are connected to its slots. For more on managing multiple windows in PyQt6, see our tutorial on creating multiple windows.

A note about QThreadPool vs QThread

The original question mentions using QThreadPool. If you're using QRunnable with a QThreadPool, the pattern is slightly different because QRunnable doesn't inherit from QObject and can't have slots directly. In that case, you typically create a separate QObject-based signals class and attach it to your runnable. For a detailed walkthrough of that approach, see Multithreading PyQt6 applications with QThreadPool.

However, for long-running background tasks that need two-way communication with the GUI (like GPIO handling), QThread with moveToThread() is usually a better fit. It gives you a proper event loop in the background thread, which means signals and slots work naturally in both directions.

Complete working example

Here's everything in a single file you can copy, run, and experiment with. If you're new to PyQt6, you may want to start with creating your first window before diving in.

python

import sys
import time

from PyQt6.QtCore import QObject, QThread, pyqtSignal, pyqtSlot
from PyQt6.QtWidgets import (
    QApplication,
    QLabel,
    QMainWindow,
    QPushButton,
    QSpinBox,
    QVBoxLayout,
    QWidget,
)


class Worker(QObject):
    """A worker that runs in a background thread."""

    data_updated = pyqtSignal(str)

    def __init__(self):
        super().__init__()
        self.running = True
        self.current_value = 0

    @pyqtSlot()
    def run(self):
        """Simulate continuous data handling."""
        while self.running:
            self.current_value += 1
            self.data_updated.emit(f"Data: {self.current_value}")
            time.sleep(1)

    @pyqtSlot(int)
    def set_value(self, value):
        """Receive a new value from the GUI."""
        self.current_value = value
        self.data_updated.emit(f"Value set to: {self.current_value}")


class SecondaryWindow(QWidget):
    """A secondary window that emits a signal when the user sets a value."""

    value_changed = pyqtSignal(int)

    def __init__(self):
        super().__init__()
        self.setWindowTitle("Secondary Window")

        layout = QVBoxLayout()

        self.label = QLabel("Set a new value for the worker:")
        layout.addWidget(self.label)

        self.spinbox = QSpinBox()
        self.spinbox.setRange(0, 1000)
        layout.addWidget(self.spinbox)

        self.button = QPushButton("Send to Worker")
        self.button.clicked.connect(self.send_value)
        layout.addWidget(self.button)

        self.setLayout(layout)

    def send_value(self):
        self.value_changed.emit(self.spinbox.value())


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Main Window")

        # Set up the UI
        layout = QVBoxLayout()

        self.status_label = QLabel("Waiting for data...")
        layout.addWidget(self.status_label)

        self.open_button = QPushButton("Open Secondary Window")
        self.open_button.clicked.connect(self.open_secondary)
        layout.addWidget(self.open_button)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

        # Keep a reference to the secondary window
        self.secondary_window = None

        # Set up the background thread and worker
        self.thread = QThread()
        self.worker = Worker()
        self.worker.moveToThread(self.thread)

        # Connect signals
        self.thread.started.connect(self.worker.run)
        self.worker.data_updated.connect(self.update_status)

        # Start the thread
        self.thread.start()

    def update_status(self, text):
        self.status_label.setText(text)

    def open_secondary(self):
        if self.secondary_window is None:
            self.secondary_window = SecondaryWindow()
            # Connect the secondary window's signal to the worker's slot
            self.secondary_window.value_changed.connect(
                self.worker.set_value
            )
        self.secondary_window.show()

    def closeEvent(self, event):
        self.worker.running = False
        self.thread.quit()
        self.thread.wait()
        super().closeEvent(event)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

When you run this, you'll see the main window counting up once per second. Click "Open Secondary Window", enter a number, and click "Send to Worker" — the worker's counter will jump to your chosen value and continue counting from there.

The secondary window communicates with the background thread entirely through signals and slots, with no direct method calls across threads. This pattern scales well — you can connect as many windows as you like to the same worker, or connect one window to multiple workers. As long as you use signals and slots for cross-thread communication, Qt handles the thread safety for you.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Streamlit Widgets — An Overview of Commonly Used Widgets in Streamlit

2026-04-24T06:00:00+00:00

Streamlit is a powerful Python library designed to build interactive web apps with minimal code. One of its core features is an extensive collection of widgets that allow users to interact with the app in various ways, such as providing inputs, triggering actions, or visualizing data. Streamlit makes it easy to create these elements with simple, intuitive syntax.

In the previous tutorial, we saw how to get started with Streamlit and run it on your local host. Here, we'll cover the main widgets available in Streamlit, explaining how they work, and how to customize them using various examples.

Getting started with Widgets Streamlit

Widgets in Streamlit are simple yet customizable. By combining multiple widgets together in different layouts, you can create interactive dashboards, data visualizations, and forms. Whether you want to include buttons, sliders, checkboxes, or display tables and plots, Streamlit offers a wide range of widgets that cater to different needs. Adding a widget to your Streamlit app is as easy as calling a single function, and customizing its behavior requires only minimal code.

In this guide, we will explore the various widgets that Streamlit offers, from basic input elements like text boxes and radio buttons to more complex visual components like plots and tables. We'll also dive into how to customize the behavior of these widgets to suit your app's specific requirements, such as adjusting slider ranges, modifying button text, and adding captions to images. By the end of this article, you'll have a solid understanding of how to leverage Streamlit widgets to enhance the interactivity and functionality of your applications.

Let's start by exploring the basic widgets Streamlit provides and how you can easily integrate them into your app. Make sure you have installed the streamlit module on your system and imported it on your Python file.

Buttons in Streamlit

Buttons are one of the most essential and commonly used components in any interactive application. In Streamlit, the st.button() widget provides an easy and effective way to allow users to trigger actions, interact with your app, or make decisions. With just a few lines of Python code, you can integrate buttons into your Streamlit app to perform tasks like data processing, changing app state, or displaying content.

The st.button() widget creates a clickable button on the interface. When clicked, it returns True, which can be used to trigger specific actions. If the button is not clicked, it returns False.

The basic syntax for creating a button in Streamlit is given below:

python

import streamlit as st
if st.button('Click Me'):
    st.write("Button clicked!")

A Streamlit button widget

In this simple example, the button's label is "Click Me". When clicked, the app prints "Button clicked!" to the interface.

The most common customization for a button is its label — the text that appears on the button. The label is the first argument you pass to the st.button() function. For example, we can change the "Click Me" to a "Submit" button.

python

import streamlit as st
if st.button('Submit'):
    st.write("Form submitted successfully!")

A Streamlit button widget with a different label

You can customize this label to suit the action you want to convey to the user. Whether it's Submit, Cancel, Run, or any custom text, Streamlit will display it as the button text

Moreover, Streamlit makes it simple to handle multiple buttons on the same page. You can define multiple st.button() widgets, each with its own label and action. Here is an example of how we can add multiple buttons.

python

import streamlit as st
if st.button('Button A'):
    st.write("Button A clicked!")

if st.button('Button B'):
    st.write("Button B clicked!")

Multiple Streamlit buttons

Similarly, you can add as many buttons as you wish.

Checkboxes in Streamlit

Checkboxes are a fundamental widget in Streamlit that allows users to toggle between two states: checked True or unchecked False. They are ideal for scenarios where you want users to make binary choices, such as showing or hiding content, enabling or disabling features, or making Yes/No decisions. It can also be used to select multiple options as the same time as well. The st.checkbox() widget is incredibly versatile and easy to implement, making it a key component in creating interactive applications.

As mentioned, the st.checkbox() widget creates a simple checkbox in your Streamlit app. When a user checks the box, it returns True, and when the box is unchecked, it returns False. Here is a basic example of checkboxes in Streamlit.

python

show_text = st.checkbox('Show text')
if show_text:
    st.write("You checked the box!")

Streamlit checkbox

In this example, the checkbox is labeled "Show text". When the user checks the box, the app displays "You checked the box!" on the interface.

The most common customization for a checkbox is its label, which appears next to the checkbox itself. This label should clearly indicate what action will occur when the checkbox is checked.

python

subscribe = st.checkbox('Subscribe to our newsletter')
if subscribe:
    st.write("Thanks for subscribing!")

Streamlit checkbox with custom label

Here, the checkbox label is customized to "Subscribe to our newsletter", and when the user checks it, a thank-you message is displayed.

By default, checkboxes in Streamlit are unchecked (False). However, you can change this by setting the value parameter to True, so that the checkbox is pre-checked when the app loads.

python

subscribe = st.checkbox('Subscribe to our newsletter', value=True)
if subscribe:
    st.write("Thanks for subscribing!")

In this case, the checkbox is checked by default, and the welcome message is shown immediately when the app starts.

Furthermore, Streamlit makes it easy to handle multiple checkboxes, each controlling different parts of your app. You can create several checkboxes, and based on their states, you can conditionally display content or execute logic.

python

option1 = st.checkbox('Enable Feature 1')
option2 = st.checkbox('Enable Feature 2')

if option1:
    st.write("Feature 1 is enabled!")
if option2:
    st.write("Feature 2 is enabled!")

Multiple Streamlit checkboxes

Sometimes, you may need to generate checkboxes dynamically, especially if the number of checkboxes depends on user input or the result of some computation.

python

options = ['Apple', 'Banana', 'Cherry']
selected = []

for fruit in options:
    if st.checkbox(fruit):
        selected.append(fruit)

st.write(f'Selected fruits: {", ".join(selected)}')

Getting Streamlit checkboxes selection state

In this example a list of fruit names is used to dynamically create a set of checkboxes. When a user checks a box, the corresponding fruit is added to a list, and the selected fruits are displayed.

Radio buttons in Streamlit

Radio buttons are an essential widget in Streamlit that allow users to select a single option from a predefined list of choices. They are perfect for scenarios where only one selection can be made at a time, such as selecting a category, choosing between modes, or answering questions. The st.radio() widget provides an intuitive and simple way for users to interact with your Streamlit application.

The st.radio() widget creates a list of radio buttons where the user can select only one option at a time. It returns the selected option, which can be used to drive various actions in the app. Let us have a look at a very simple example of a radio button.

python

choice = st.radio('Choose an option:', ['Option 1', 'Option 2', 'Option 3'])
st.write(f'You selected: {choice}')

Streamlit radio buttons

In this example:

A label "Choose an option:" is provided.
The user can select one of three options: "Option 1", "Option 2", or "Option 3".
The app displays the selected option below the radio buttons.

By default, the first option in the list of radio buttons is selected. However, you can customize this by setting the index parameter, which specifies which option should be selected when the app loads.

python

travel_mode = st.radio('Preferred mode of travel:', ['Car', 'Bike', 'Plane'], index=2)
st.write(f'You selected: {travel_mode}')

Streamlit radio buttons with default selection

The index=2 means the third option ("Plane") is selected by default when the app is loaded.

Select box in Streamlit

A select box in Streamlit is a widget that lets users choose a single option from a dropdown list. This widget is perfect for situations where you have a predefined list of options but want to save space on your interface by not displaying all the options upfront. The st.selectbox() widget is highly customizable and can be used for anything from simple selections to dynamically populated lists. It's ideal for situations where you want to offer multiple choices, but only display the currently selected item. Let us create a simple dropdown menu with three options.

python

option = st.selectbox('Choose an option:', ['Option 1', 'Option 2', 'Option 3'])
st.write(f'You selected: {option}')

Streamlit select box

In this example:

A label "Choose an option:" is provided.
The user can select one of the options from the dropdown list: "Option 1", "Option 2", or "Option 3".
The app displays the selected option.

By default, the first item in the list of options is selected in a select box. However, you can specify a different default selection by setting the index parameter. The index corresponds to the zero-based position of the option in the list.

python

city = st.selectbox('Select your city:', ['New York', 'London', 'Paris', 'Tokyo'], index=2)
st.write(f'You selected: {city}')

When you run this code, you will notice that, Paris will be selected as city because it is at index 2.

Slider in Streamlit

Sliders are a popular widget in Streamlit that allows users to select values by dragging a handle across a range. They are perfect for collecting numerical inputs or setting parameters like dates, time, and ranges. Streamlit's st.slider() widget provides a flexible and easy-to-use interface for adding sliders to your app, enabling users to interactively choose values with precision. It can handle integers, floats, dates, and times, making it highly versatile for various use cases.

Let us create a simple slider where a user can select any number from 0 to 100.

python

value = st.slider('Select a value:', 0, 100)
st.write(f'You selected: {value}')

Streamlit slider widget

By default, the slider handle is set to the minimum value of the range, but you can specify a default value by providing a value argument. This is useful when you want the slider to start at a specific position.

python

temperature = st.slider('Set the temperature:', -50, 50, value=20)
st.write(f'Temperature set to: {temperature}°C')

Streamlit slider widget with default value

By default, the 20 will be selected as set temperature.

Sliders in Streamlit can handle both integers and floating-point numbers. To use floating-point values, you simply specify a range with float values. You can also control the step size between values using the step parameter.

python

price = st.slider('Select a price:', 0.0, 1000.0, step=0.5)
st.write(f'Price selected: ${price}')

Streamlit float slider widget

In this example:

The slider lets the user select a price between 0.0 and 1000.0.
The step=0.5 ensures that the slider increments or decrements by 0.5 units.

Streamlit's slider widget also allows users to select a range of values, which is particularly useful when you need two values (e.g., a start and end date, or a minimum and maximum range). To do this, provide a tuple as the value argument.

python

salary_range = st.slider('Select a salary range:', 20000, 100000, (30000, 80000))
st.write(f'Selected salary range: ${salary_range[0]} - ${salary_range[1]}')

Streamlit range slider widget

Here, the slider has a range from 20000 to 100000. The user can select a minimum and maximum value for the salary range (initially set between 30000 and 80000).

Apart from that, Streamlit sliders can also handle date and time values, which is especially useful when users need to select a specific day or time range. You can create sliders with datetime.date and datetime.time objects to allow users to make date-based selections.

python

import streamlit as st
import datetime

date = st.slider('Select a date:', datetime.date(2020, 1, 1), datetime.date(2024, 12, 31), value=datetime.date(2023, 1, 1))

Streamlit date slider

In this example, the user can select a date between January 1, 2020, and December 31, 2024. The default value is set to January 1, 2023.

You can use sliders with any other widgets or functions to make it more dynamic and interactive. For example, we can combine them with conditional logic to adjust the behavior or content of an app based on the selected value. This is particularly useful for creating dynamic and interactive experiences.

python

rating = st.slider('Rate our service:', 1, 5)

if rating <= 2:
    st.write('We are sorry to hear that. Please let us know how we can improve.')
else:
    st.write('Thank you for your feedback!')

Streamlit slider interactivity

The slider allows users to rate a service between 1 and 5. Based on the rating, different messages are displayed.

Different input options in Streamlit

In Streamlit, input options are essential for creating interactive applications, allowing users to interact with data and visualizations dynamically. Streamlit offers a variety of input widgets that cater to different types of data and user interactions. Below are the main input options that we will be discussing in this section:

Text Input: The st.text_input() widget allows users to enter single-line text data. It's useful for collecting short information like names, email addresses, or any single-line text input.
Text Area: For multi-line input, st.text_area() is the preferred choice. It provides users with a larger space for entering longer content, like descriptions, notes, or code snippets.
Number Input: Streamlit provides the st.number_input() widget for numerical inputs. Users can specify integer or float values within a defined range and step size, which makes it suitable for settings like entering age, prices, or percentages.
Date and Time Input: For handling date and time, Streamlit provides the st.date_input() and st.time_input() widgets, allowing users to pick dates and times easily. This is useful for scheduling or filtering data by time ranges.

Now, let us discuss each of these options in details by taking examples.

Date and Time Input

Among its many features, Streamlit provides robust support for handling date and time inputs, allowing developers to easily integrate date and time pickers into their applications. This is useful in a wide variety of contexts, such as scheduling applications, time series analysis, filtering data based on time ranges, or tracking events.

The st.date_input() widget in Streamlit provides a simple and intuitive interface for users to select dates. This widget can be used to input a single date or a range of dates. The basic syntax of date_input() function is given below will possible parameter values.

python

st.date_input("Date", value=None, min_value=None, max_value=None, key=None, help=None, on_change=None)

Streamlit date input

Let us explore the parameters in turn:

label: The label to display alongside the widget.
value: The default date(s) to show in the widget. This can be a single date or a tuple of two dates for range selection. Defaults to today's date.
min_value: The earliest date that can be selected. Defaults to no minimum.
max_value: The latest date that can be selected. Defaults to no maximum.
key: An optional key that uniquely identifies this widget.
help: A tooltip that displays when the user hovers over the widget.
on_change: A callback function that runs when the input changes.

In addition to that, you can also use st.date_input() to allow users to pick a range of dates by passing a tuple of two datetime.date objects as the default value.

python

import streamlit as st
import datetime

# Date range input
start_date = datetime.date(2023, 9, 1)
end_date = datetime.date(2023, 9, 30)
date_range = st.date_input("Select a date range", (start_date, end_date))
st.write(f"Start date: {date_range[0]}")
st.write(f"End date: {date_range[1]}")

Streamlit date range input

In this case, the user can select a range of dates. The widget will return a tuple containing the start and end dates.

On the other hand, the st.time_input() widget allows users to select a specific time. This widget is useful in scenarios like scheduling events or setting alarms. Here is the simple syntax off time_input() function with its possible parameter values.

python

st.time_input(label="Time", value=None, key=None, help=None, on_change=None)

Streamlit time input

The parameters in the time_input functions:

label: The label displayed next to the widget.
value: The default time shown in the widget. This can be a datetime.time object. Defaults to the current time.
key: An optional key that uniquely identifies the widget.
help: Tooltip displayed when the user hovers over the widget.
on_change: A callback function that runs when the input changes.

In many applications, you'll need both date and time inputs together. Although Streamlit doesn't provide a single widget for selecting both date and time, you can combine the st.date_input() and st.time_input() widgets to achieve this functionality.

python

import streamlit as st
import datetime

# Date input
date = st.date_input("Pick a date", datetime.date.today())
# Time input
time = st.time_input("Pick a time", datetime.time(9, 00))

# Combine date and time
selected_datetime = datetime.datetime.combine(date, time)
st.write(f"Selected date and time: {selected_datetime}")

Combining Streamlit widgets for selecting date and time

This code lets the user select both a date and a time, then combines them into a single datetime.datetime object.

Text and area input

One of the essential features of any web app is gathering user input, and Streamlit provides several widgets to capture user input easily. Among them, text input widgets play a crucial role in allowing users to input free-form text data. In this article, we will dive into Streamlit's text input widgets and explore their capabilities, practical applications, and customization options.

Streamlit offers two primary widgets for capturing text input:

Single-Line Text Input: Captured using the st.text_input() widget.
Multi-Line Text Area: Captured using the st.text_area() widget.

Both widgets are used to gather text-based input from users but differ in the amount of text they are designed to handle. Let's take a closer look at each of these widgets.

The st.text_input() widget allows users to input a single line of text. This is ideal for cases where you want to gather short responses such as names, email addresses, usernames, search queries, or small pieces of data.

python

# Single-line text input
name = st.text_input("Enter your name")
st.write(f"Hello, {name}!")

Streamlit text input widget

This example creates a simple input box where users can enter their names. The app then displays a message using the entered text.

In some cases, we may need to limit the total number of characters entered by the user. So, we can use the max_charsparameter as shown below:

python

# Text input with character limit
username = st.text_input("Enter your username", max_chars=15)
st.write(f"Your username is: {username}")

This is similar to the previous example, but this time the user is not allowed to enter characters more than 15. In the text_input() function, we can also specify the type of text we want the user to enter. For example, if we want a user to enter an email and password, we can specify those as shown below:

python

email = st.text_input("Enter your email")
st.write(f"Email entered: {email}")
password = st.text_input("Enter your password", type='password')
st.write(f"Password length: {len(password)} characters")

Streamlit password input widget

As shown above, when we enter the password, it will not be visible.

The st.text_area() widget is ideal when you need to capture longer inputs or multi-line text, such as feedback, code snippets, or detailed descriptions. It provides users with a resizable text area where they can enter more extensive information

python

# Multi-line text area
feedback = st.text_area("Your feedback", "Enter your comments here...")
st.write(f"Your feedback: {feedback}")

Streamlit text area for text input

In this example, the text area allows the user to enter multiple lines of text. The entered feedback is then displayed. In a similar way as we did before, you can limit the max number of characters by assigning a value to the max_chars parameter.

Number Input in Streamlit

The st.number_input() widget allows users to input numbers, offering several customization options like setting minimum and maximum values, adjusting step increments, and choosing between integers and floating-point numbers. This widget is particularly useful for inputs like prices, quantities, percentages, or any scenario where numerical precision is required.

The simplest form of the st.number_input() widget involves asking the user to input a number without setting any constraints like minimum or maximum values.

python

age = st.number_input("Enter your age")
st.write(f"Your age is: {age}")

Streamlit numeric input

In this example, the widget accepts any number, and the user's input is displayed back on the screen.

You can restrict the input to a certain range by specifying the min_value and max_value parameters. This is particularly useful when you need to validate the input against specific boundaries.

python

# Number input with a range
rating = st.number_input("Rate your experience", min_value=1, max_value=5)
st.write(f"Your rating is: {rating}")

Numeric input with validation

In this example, the user can only select a rating between 1 and 5, ensuring valid input. You can set a default value that appears in the input box when the app first loads, and you can also define how much the value should increase or decrease when the user interacts with the widget.

python

# Number input with default value and step size
quantity = st.number_input("Select quantity", min_value=0, max_value=100, value=10, step=5)
st.write(f"You have selected: {quantity} units")

Numeric input with validation and step size

In this example, the widget starts with a default value of 10, and the user can adjust the value in increments of 5, from 0 to 100.

File uploader in Streamlit

st.file_uploader() widget, which allows users to upload files directly into your Streamlit app. This functionality is vital in many applications, such as data analysis tools, machine learning models, and document processing systems. This widget is a convenient tool for enabling users to upload files of various types, such as text files, CSVs, images, PDFs, and more. Once uploaded, the files can be processed or analyzed directly within the Streamlit app.

The simplest use case of st.file_uploader() is to upload a single file of a specific type.

python

import pandas as pd

# Single file uploader for CSV files
uploaded_file = st.file_uploader("Upload a CSV file", type="csv")

if uploaded_file is not None:
    df = pd.read_csv(uploaded_file)
    st.write(df)

Upload CSV files

In this example, the user can upload a CSV file, and the app reads and displays the contents using the pandas library.

We can also upload images and show them in our web app. For images, we need to specify the type of images as shown in the example below:

python

import streamlit as st
from PIL import Image

# Upload an image file
uploaded_image = st.file_uploader("Upload an image", type=["png", "jpg", "jpeg"])

if uploaded_image is not None:
    image = Image.open(uploaded_image)
    st.image(image, caption="Uploaded Image", use_column_width=True)

Upload image files

Here, users can upload image files in formats like PNG, JPG, or JPEG. Once uploaded, the app uses the Pillow library to open and display the image.

Furthermore, you can use the accept_multiple_files parameter to allow users to upload several files at once. This is useful when handling bulk uploads or cases where multiple files need to be processed together.

python

# Multiple file uploader for text files
uploaded_files = st.file_uploader("Upload multiple text files", type="txt", accept_multiple_files=True)

if uploaded_files:
    for uploaded_file in uploaded_files:
        st.write(f"File name: {uploaded_file.name}")
        content = uploaded_file.read().decode("utf-8")
        st.write(content)

Uploading multiple files

In this example, the user can upload multiple text files. The app reads and displays the contents of each file.

Streamlit also allows you to validate uploaded files based on specific conditions, such as file size, format, or content.

python

uploaded_file = st.file_uploader("Upload a file")

if uploaded_file is not None:
    # Check file size (less than 2 MB)
    file_size = uploaded_file.size
    if file_size > 2 * 1024 * 1024:
        st.error("File size exceeds 2 MB limit!")
    else:
        st.success("File uploaded successfully.")
        st.write(f"File size: {file_size} bytes")

Uploading file too large

As you can see, the file was not uploaded because it exceeds the max size.

Conclusion

Streamlit's widget system is a powerful and intuitive way to add interactivity to web applications. From simple text and number inputs to more complex file uploaders and sliders, Streamlit provides a wide range of widgets that allow users to seamlessly interact with your app. These widgets can be easily integrated into data-driven applications, enabling users to input data, upload files, and adjust parameters in real-time.

Streamlit widgets are designed to be highly customizable, offering various configuration options like minimum and maximum values, step sizes, file type restrictions, and dynamic callbacks. With minimal code, developers can create sophisticated, interactive applications that enhance user experience and make complex workflows more accessible.

Checkboxes in Table Views with a Custom Model — Show checkboxes for boolean values in PyQt/PySide table views

2026-04-22T09:00:00+00:00

I have a QTableView with a custom QAbstractTableModel, and I want to add a column of checkboxes. Should I create a custom delegate class for the checkbox, or is there a simpler way to do this?

You can use a custom delegate to draw a checkbox widget, but you don't have to. Qt provides a built-in mechanism for this: Qt.CheckStateRole. By returning Qt.Checked or Qt.Unchecked from your model's data() method, Qt will render a checkbox automatically — no delegate required.

Let's walk through how this works, starting with a simple display and then adding some interactivity.

Displaying checkboxes using Qt.CheckStateRole

The simplest way to add checkboxes to a QTableView is to handle Qt.CheckStateRole in your model's data() method. When Qt asks your model for data with this role, returning Qt.Checked or Qt.Unchecked tells Qt to draw a checkbox in that cell.

Here's a minimal example that shows a checked checkbox in every cell:

python

def data(self, index, role):
    if role == Qt.DisplayRole:
        value = self._data[index.row()][index.column()]
        return str(value)

    if role == Qt.CheckStateRole:
        return Qt.Checked

This produces a table where every cell has both text and a checked checkbox:

In a real application, you would return Qt.Checked or Qt.Unchecked based on actual boolean values in your data. You might also restrict checkboxes to a specific column — for example, one that holds True/False values — rather than showing them everywhere.

Making checkboxes toggleable

Displaying checkboxes is a good start, but users will expect to be able to click them. To make checkboxes interactive, you need three things:

A data store for the check state — a list (or column) that tracks which items are checked.
Qt.ItemIsUserCheckable returned from flags() — this tells Qt that the cell supports toggling.
A setData() implementation for Qt.CheckStateRole — this stores the updated state when the user clicks a checkbox.

Let's put all of this together in a complete example.

python

import sys

from PyQt6 import QtCore, QtGui, QtWidgets
from PyQt6.QtCore import Qt


class TableModel(QtCore.QAbstractTableModel):

    def __init__(self, data, checked):
        super().__init__()
        self._data = data
        self._checked = checked

    def data(self, index, role):
        if role == Qt.ItemDataRole.DisplayRole:
            value = self._data[index.row()][index.column()]
            return str(value)

        if role == Qt.ItemDataRole.CheckStateRole:
            checked = self._checked[index.row()][index.column()]
            if checked:
                return Qt.CheckState.Checked
            return Qt.CheckState.Unchecked

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.CheckStateRole:
            checked = value == Qt.CheckState.Checked.value
            self._checked[index.row()][index.column()] = checked
            self.dataChanged.emit(index, index, [role])
            return True
        return False

    def rowCount(self, index):
        return len(self._data)

    def columnCount(self, index):
        return len(self._data[0])

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsUserCheckable
        )


class MainWindow(QtWidgets.QMainWindow):

    def __init__(self):
        super().__init__()

        self.table = QtWidgets.QTableView()

        data = [
            [1, 9, 2],
            [1, 0, -1],
            [3, 5, 2],
            [3, 3, 2],
            [5, 8, 9],
        ]

        checked = [
            [True, True, True],
            [False, False, False],
            [True, False, False],
            [True, False, True],
            [False, True, True],
        ]

        self.model = TableModel(data, checked)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)


app = QtWidgets.QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Run this and you'll see a table with checkboxes next to every value. Clicking any checkbox toggles it on and off, and the underlying checked list is updated accordingly.

Storing check state separately

The checked list mirrors the structure of the data list — each cell has a corresponding True or False value. This keeps the boolean check state separate from the data.

You could store it in the same data structure, as a [bool, data_value] nested list, or tuple if you like.

Returning the check state in `data()`

When Qt asks for Qt.ItemDataRole.CheckStateRole, we look up the boolean value for that cell and return either Qt.CheckState.Checked or Qt.CheckState.Unchecked:

python

if role == Qt.ItemDataRole.CheckStateRole:
    checked = self._checked[index.row()][index.column()]
    if checked:
        return Qt.CheckState.Checked
    return Qt.CheckState.Unchecked

For these return X if True, otherwise return Y type returns you can also use and X if bool else Y expression.

python

if role == Qt.ItemDataRole.CheckStateRole:
    checked = self._checked[index.row()][index.column()]
    return Qt.CheckState.Checked if checked else Qt.CheckState.Unchecked

Handling user clicks in `setData()`

When the user clicks a checkbox, Qt calls setData() with the new value and the Qt.ItemDataRole.CheckStateRole role. We compare the incoming value to Qt.CheckState.Checked.value to determine whether the box was checked or unchecked, then store the result:

python

def setData(self, index, value, role):
    if role == Qt.ItemDataRole.CheckStateRole:
        checked = value == Qt.CheckState.Checked.value
        self._checked[index.row()][index.column()] = checked
        self.dataChanged.emit(index, index, [role])
        return True
    return False

Notice the self.dataChanged.emit(...) call — this notifies the view that the data has changed so it can redraw the cell. Always emit this signal when you modify data in setData().

Enabling user interaction with `flags()`

The flags() method tells Qt what the user can do with each cell. Including Qt.ItemFlag.ItemIsUserCheckable is what makes the checkbox clickable:

python

def flags(self, index):
    return (
        Qt.ItemFlag.ItemIsSelectable
        | Qt.ItemFlag.ItemIsEnabled
        | Qt.ItemFlag.ItemIsUserCheckable
    )

Without this flag, the checkbox will still appear (because you're returning data for CheckStateRole), but the user won't be able to toggle it.

Showing checkboxes in only one column

In many applications, you only want checkboxes in a specific column. You can achieve this by checking index.column() in your data() and flags() methods. For example, to show checkboxes only in column 2:

python

def data(self, index, role):
    if role == Qt.ItemDataRole.DisplayRole:
        value = self._data[index.row()][index.column()]
        return str(value)

    if role == Qt.ItemDataRole.CheckStateRole:
        if index.column() == 2:
            checked = self._checked[index.row()]
            if checked:
                return Qt.CheckState.Checked
            return Qt.CheckState.Unchecked

def flags(self, index):
    flags = Qt.ItemFlag.ItemIsSelectable | Qt.ItemFlag.ItemIsEnabled
    if index.column() == 2:
        flags |= Qt.ItemFlag.ItemIsUserCheckable
    return flags

In this case, self._checked would be a simple one-dimensional list (one boolean per row) rather than a 2D list.

Summary

To add checkboxes to a QTableView with a custom QAbstractTableModel:

Handle Qt.ItemDataRole.CheckStateRole in data() to display checkboxes based on boolean values.
Return Qt.ItemFlag.ItemIsUserCheckable from flags() to make checkboxes interactive.
Implement setData() for Qt.ItemDataRole.CheckStateRole to store the updated state when the user clicks, and emit dataChanged to keep the view in sync.

This approach works natively with Qt's model/view architecture and avoids the complexity of writing a custom delegate. For a more complete guide to displaying data in table views — including using numpy and pandas data sources — see our QTableView with ModelViews tutorial. If you want to show only an icon without text in specific cells, see how to show only an icon in a QTableView cell. You can also learn how to create your own custom widgets for more advanced UI needs.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

What does @pyqtSlot() do? — Is the pyqtSlot decorator even necessary?

2026-01-12T06:00:00+00:00

When working with Qt slots and signals in PyQt6 you will discover the @pyqtSlot decorator. This decorator is used to mark a Python function or method as a slot to which a Qt signal can be connected. However, as you can see in our signals and slots tutorials you don't have to use this. Any Python function or method can be used, normally, as a slot for Qt signals. But elsewhere, in our threading tutorials we do use it.

What's going on here?

Why do you sometimes use @pyqtSlot but usually not?
What happens when you omit the @pyqtSlot decorator?
Are there times when @pyqtSlot is required?

What does the PyQt6 documentation say about @pyqtSlot?

The PyQt6 documentation has a good explanation:

Although PyQt6 allows any Python callable to be used as a slot when connecting signals, it is sometimes necessary to explicitly mark a Python method as being a Qt slot and to provide a C++ signature for it. PyQt6 provides the pyqtSlot() function decorator to do this.

Connecting a signal to a decorated Python method has the advantage of reducing the amount of memory used and is slightly faster.

From the above we see that:

Any Python callable can be used as a slot when connecting signals.
It is sometimes necessary to explicitly mark a Python method as being a Qt slot and to provide a C++ signature for it.
There is a side-benefit in that marking a function or method with pyqtSlot() reduces the amount of memory used, and makes the slot faster.

When is @pyqtSlot necessary?

Sometimes necessary is a bit vague. In practice the only situation where you need to use @pyqtSlot decorators is when working with threads. This is because of a difference in how signal connections are handled in decorated vs. undecorated slots.

If you decorate a method with @pyqtSlot then that slot is created as a native Qt slot, and behaves identically to a C++ slot.
If you don't decorate the method then PyQt6 will create a "proxy" object wrapper which provides a native slot to Qt.

In normal use this is fine, aside from the performance impact (see below). But when working with threads, there is a complication: is the proxy object created on the GUI thread or on the runner thread? If it ends up on the wrong thread, this can lead to segmentation faults. Using the @pyqtSlot decorator side-steps this issue, because no proxy is created.

When updating my PyQt6 book I wondered -- is this still necessary?! -- and tested removing it from the examples. Many examples continue to work, but some failed. To be safe, always use @pyqtSlot decorators on your QRunnable.run methods.

@pyqtSlot performance: does it make a difference?

The PyQt6 documentation notes that using native slots "has the advantage of reducing the amount of memory used and is slightly faster". But how much faster is it really, and does decorating slots actually save much memory?

We can test this directly by using this script from Oliver L Schoenborn. Updating for PyQt6 (replace PyQt5 with PyQt6 and it will work as-is) and running this we get the following results:

See the original results for PyQt5 for comparison.

First the results for the speed of emitting signals when connected to a decorated slot, vs. a non-decorated slot.

python

Raw slot mean, stddev:  0.578 0.024
Pyqt slot mean, stddev: 0.587 0.021
Percent gain with pyqtSlot: -2 %

The result shows @pyqtSlot as 2% slower, but this is negligible (the original data on PyQt5 also showed no difference). So, using @pyqtSlot will have no noticeable impact on the speed of signal handling in your applications.

Next are the results for establishing connections. This shows the speed and memory usage of connecting to decorated vs. non-decorated slots.

python

Comparing mem and time required to create 10000000 connections, 1000 times

Measuring for 1000000 connections
              # connects     mem (bytes)          time (sec)
Raw         :   1000000      949186560 (905MB)    9.02
Pyqt Slot   :   1000000       48500736 ( 46MB)    1.52
Ratios      :                       20               6

The results show that decorated slots are about 6x faster to connect to. This sounds like a big difference, but it would only be noticeable if an application was connecting a considerable number of signals. Based on these numbers, if you connected 100 signals the total execution time difference would be 0.9 ms vs. 0.15 ms. This is negligible, not to mention imperceptible.

Perhaps more significant is that using raw connections uses 20x the memory of decorated connections. Again though, bear in mind that for a more realistic upper limit of connections (100) the actual difference here is 0.09MB vs. 0.004MB.

The bottom line: don't expect any dramatic improvements in performance or memory usage from using @pyqtSlot decorators, unless you're working with insanely large numbers of signals or making regular connections you won't see any difference at all. That said, decorating your slots is an easy win if you need it.

Using @pyqtSlot to overload signal types

In Qt, signals can be used to transmit more than one type of data by overloading signals and slots with different types.

For example, with the following code the my_slot_fn will only receive signals which match the signature of two int values.

python

@pyqtSlot(int, int)
def my_slot_fn(a, b):
    pass

This is a legacy of Qt5 and not recommended in new code. In Qt6 all of these signals have been replaced with separate signals with distinct names for different types. I recommend you follow the same approach in your own code for the sake of simplicity.

Conclusion

The @pyqtSlot decorator can be used to mark Python functions or methods as Qt slots. This decorator is only required on slots which may be connected to across threads, for example the run method of QRunnable objects. For all other slots it can be omitted. There is a very small performance benefit to using it, which you may want to consider when your application makes a large number of signal-slot connections.

To summarize when to use @pyqtSlot:

Threading — Always use @pyqtSlot on QRunnable.run methods and any slot called across threads to avoid segmentation faults.
Performance — For most applications the performance gain is negligible, but it can help if you have thousands of signal connections.
Signal overloading — You can use @pyqtSlot to restrict a slot to a specific type signature, though this pattern is discouraged in Qt6.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With Flet for GUI Development — Your First Steps With the Flet Library for Desktop and Web Python GUIs

2025-12-15T06:00:00+00:00

Getting started with a new GUI framework can feel daunting. This guide walks you through the essentials of Flet, from installation and a first app to widgets, layouts, and event handling.

With Flet, you can quickly build modern, high‑performance desktop, web, and mobile interfaces using Python.

What Is Flet? A Cross-Platform Python GUI Framework

Flet is a cross-platform GUI framework for Python. It enables the development of interactive applications that run as native desktop applications on Windows, macOS, and Linux. Flet apps also run in the browser and even as mobile apps. Flet uses Flutter under the hood, providing a modern look and feel with responsive layouts.

The library's key features include:

Modern, consistent UI across desktop, web, and mobile
No HTML, CSS, or JS required, only write pure Python
Rich set of widgets for input, layout, data display, and interactivity
Live reload for rapid development
Built-in support for theming, navigation, and responsive design
Easy event handling and state management

Flet is great for building different types of GUI apps, from utilities and dashboards to data-science tools, business apps, and even educational or hobby projects.

Installing Flet

You can install Flet from PyPI using the following pip command:

$ pip install flet

This command downloads and installs Flet into your current Python environment. That's it! You can now write your first app.

Writing Your First Flet GUI App

To build a Flet app, you typically follow these steps:

Import flet and define a function that takes a Page object as an argument.
Add UI controls (widgets) to the page.
Use flet.app() to start the app by passing the function as an argument.

Here's a quick Hello, World! application in Flet:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet First App"
    page.window.width = 200
    page.window.height = 100
    page.add(ft.Text("Hello, World!"))

ft.app(target=main)

In the main() function, we get the page object as an argument. This object represents the root of our GUI. Then, we set the title and window size and add a Text control that displays the "Hello, World!" text.

Use page.add() to add controls (UI elements or widgets) to your app. To manipulate the widgets, you can use page.controls, which is a list containing the controls that have been added to the page.

Run it! Here's what your first app looks like.

First Flet GUI application

You can run a Flet app as you'd run any Python app in the terminal. Additionally, Flet allows you to use the flet run command for live reload during development.

Exploring Flet Controls (Widgets)

Flet includes a wide variety of widgets, known as controls, in several categories. Some of these categories include the following:

In the following sections, you'll code simple examples showcasing a sample of each category's controls.

Flet Button Controls

Buttons are key components in any GUI application. Flet has several types of buttons that we can use in different situations, including the following:

FilledButton: A filled button without a shadow. Useful for important, final actions that complete a flow, like Save or Confirm.
ElevatedButton: A filled tonal button with a shadow. Useful when you need visual separation from a patterned background.
FloatingActionButton: A Material Design floating action button.

Here's an example that showcases these types of buttons:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Buttons Demo"
    page.window.width = 200
    page.window.height = 200

    page.add(ft.ElevatedButton("Elevated Button"))
    page.add(ft.FilledButton("Filled Button"))
    page.add(ft.FloatingActionButton(icon=ft.Icons.ADD))

ft.app(target=main)

Here, we call the add() method on our page object to add instances of ElevatedButton, FilledButton, and FloatingActionButton. Flet arranges these controls vertically by default.

Run it! You'll get a window that looks like the following.

Flet buttons demo

Input and Selection Controls

Input and selection controls enable users to enter data or select values in your app's GUI. Flet provides several commonly used controls in this category, including the following:

TextField: A common single-line or multi-line text entry control.
Dropdown: A selection control that lets users pick a value from a list of options.
Checkbox: A control for boolean input, often useful for preferences and agreement toggles.
Radio: A selection radio button control commonly used inside a RadioGroup to choose a single option from a set.
Slider: A control for selecting a numeric value along a track.
Switch: A boolean on/off toggle.

Here's an example that showcases some of these input and selection controls:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Input and Selections Demo"
    page.window.width = 360
    page.window.height = 320

    name = ft.TextField(label="Name")
    agree = ft.Checkbox(label="I agree to the terms")
    level = ft.Slider(
        label="Experience level",
        min=0,
        max=10,
        divisions=10,
        value=5,
    )
    color = ft.Dropdown(
        label="Favorite color",
        options=[
            ft.dropdown.Option("Red"),
            ft.dropdown.Option("Green"),
            ft.dropdown.Option("Blue"),
        ],
    )
    framework = ft.RadioGroup(
        content=ft.Column(
            [
                ft.Radio(value="Flet", label="Flet"),
                ft.Radio(value="Tkinter", label="Tkinter"),
                ft.Radio(value="PyQt6", label="PyQt6"),
                ft.Radio(value="PySide6", label="PySide6"),
            ]
        )
    )
    notifications = ft.Switch(label="Enable notifications", value=True)

    page.add(
        ft.Text("Fill in the form and adjust the options:"),
        name,
        agree,
        level,
        color,
        framework,
        notifications,
    )

ft.app(target=main)

After setting the window's title and size, we create several input controls:

A TextField for the user's name
A Checkbox to agree to the terms
A Slider to select an experience level from 0 to 10
A Dropdown to pick a favorite color
A RadioGroup with several framework choices
A Switch to enable or disable notifications, which defaults to ON

We add all these controls to the page using page.add(), preceded by a simple instruction text. Flet lays out the controls vertically (the default) in the order you pass them.

Run it! You'll see a simple form that uses text input, dropdowns, checkboxes, radio buttons, sliders, and switches.

Flet input and selection controls demo

Navigation Controls

Navigation controls allow users to move between different sections or views within an app. Flet provides several navigation controls, including the following:

NavigationBar: A bottom navigation bar with multiple destinations, which is useful for switching between three to five primary sections of your app.
AppBar: A top app bar that can display a title, navigation icon, and action buttons.

Here's an example that uses NavigationBar to navigate between different views:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Navigation Bar Demo"
    page.window.width = 360
    page.window.height = 260

    info = ft.Text("You are on the Home tab")

    def on_nav_change(e):
        idx = page.navigation_bar.selected_index
        if idx == 0:
            info.value = "You are on the Home tab"
        elif idx == 1:
            info.value = "You are on the Search tab"
        else:
            info.value = "You are on the Profile tab"
        page.update()

    page.navigation_bar = ft.NavigationBar(
        selected_index=0,
        destinations=[
            ft.NavigationBarDestination(icon=ft.Icons.HOME, label="Home"),
            ft.NavigationBarDestination(icon=ft.Icons.SEARCH, label="Search"),
            ft.NavigationBarDestination(icon=ft.Icons.PERSON, label="Profile"),
        ],
        on_change=on_nav_change,
    )

    page.add(
        ft.Container(content=info, alignment=ft.alignment.center, padding=20),
    )

ft.app(target=main)

The NavigationBar has three tabs: Home, Search, and Profile, each with a representative icon that you provide using ft.Icons. Assigning this bar to page.navigation_bar tells Flet to display it as the app's bottom navigation component.

The behavior of the bar is controlled by the on_nav_change() callback (more on this in the section on events and callbacks). Whenever the user clicks a tab, Flet calls on_nav_change(), which updates the text with the appropriate message.

Run it! Click the different tabs to see the text on the page update as you navigate between sections.

Flet navigation bar demo

Information Display Controls

We can use information-display controls to present content to the user, such as text, images, and rich list items. These controls help communicate status, context, and details without requiring user input.

Some common information-display controls include the following:

Text: The basic control for showing labels, paragraphs, and other readable text.
Image: A control for displaying images from files, assets, or URLs.

Here's an example that combines these controls:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Information Displays Demo"
    page.window.width = 340
    page.window.height = 400

    header = ft.Text("Latest image", size=18)

    hero = ft.Image(
        src="https://picsum.photos/320/320",
        width=320,
        height=320,
        fit=ft.ImageFit.COVER,
    )

    page.add(
        header,
        hero,
    )

ft.app(target=main)

In main(), we create a Text widget called header to show "Latest image" with a larger font size. The hero variable is an Image control that loads an image from the URL https://picsum.photos/320/320.

We use a fixed width and height together with ImageFit.COVER so that the image fills its box while preserving aspect ratio and cropping if needed.

Run it! You'll see some text and a random image from Picsum.photos.

Flet information display demo

Dialogs, Alerts, and Panels

Dialogs, alerts, and panels enable you to draw attention to important information or reveal additional details without leaving the current screen. They are useful for confirmations, warnings, and expandable content.

Some useful controls in this category are listed below:

AlertDialog: A modal dialog that asks the user to acknowledge information or make a decision.
Banner: A prominent message bar displayed at the top of the page for important, non-modal information.
DatePicker: A control that lets the user pick a calendar date in a pop-up dialog.
TimePicker: A control for selecting a time of day from a dialog-style picker.

Here's an example that shows an alert dialog to ask for exit confirmation:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Dialog Demo"
    page.window.width = 300
    page.window.height = 300

    def on_dlg_button_click(e):
        if e.control.text == "Yes":
            page.window.close()
        page.close(dlg_modal)

    dlg_modal = ft.AlertDialog(
        modal=True,
        title=ft.Text("Confirmation"),
        content=ft.Text("Do you want to exit?"),
        actions=[
            ft.TextButton("Yes", on_click=on_dlg_button_click),
            ft.TextButton("No", on_click=on_dlg_button_click),
        ],
        actions_alignment=ft.MainAxisAlignment.END,
    )

    page.add(
        ft.ElevatedButton(
            "Exit",
            on_click=lambda e: page.open(dlg_modal),
        ),
    )

ft.app(target=main)

In this example, we first create an AlertDialog with a title, some content text, and two action buttons labeled Yes and No.

The on_dlg_button_click() callback checks which button was clicked and closes the application window if the user selects Yes. The page shows a single Exit button that opens the dialog. After the user responds, the dialog is closed.

Run it! Try clicking the button to open the dialog. You'll see a window similar to the one shown below.

Flet dialog demo

Laying Out Your GUI With Flet Layouts

Controls in this category are often described as container controls that can hold child controls. These controls enable you to arrange widgets on an app's GUI to create a well-organized and functional interface.

Flet has many container controls. Here are some of them:

Page: This control is the root of the control hierarchy or tree. It is also listed as an adaptive container control.
Column: A container control used to arrange child controls in a column.
Row: A container control used to arrange child controls horizontally in a row.
Container: A container control that allows you to modify its size (e.g., height) and appearance.
Stack: A container control where properties like bottom, left, right, and top allow you to place children in specific positions.
Card: A container control with slightly rounded corners and an elevation shadow.

By default, Flet stacks widgets vertically using the Column container. Here's an example that demonstrates basic layout options in Flet:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Layouts Demo"
    page.window.width = 250
    page.window.height = 300

    main_layout = ft.Column(
        [
            ft.Text("1) Vertical layout:"),
            ft.ElevatedButton("Top"),
            ft.ElevatedButton("Middle"),
            ft.ElevatedButton("Bottom"),
            ft.Container(height=12),  # Spacer

            ft.Text("2) Horizontal layout:"),
            ft.Row(
                [
                    ft.ElevatedButton("Left"),
                    ft.ElevatedButton("Center"),
                    ft.ElevatedButton("Right"),
                ]
            ),
        ],
    )

    page.add(main_layout)

ft.app(target=main)

In this example, we use a Column object as the app's main layout. This layout stacks text labels and buttons vertically, while the inner Row object arranges three buttons horizontally. The Container object with a fixed height acts as a spacer between the vertical and horizontal sections.

Run it! You'll get a window like the one shown below.

Flet layouts demo

Handling Events and Callbacks in Flet

Flet uses event handlers to manage user interactions and perform actions. Most controls accept an on_* argument, such as on_click or on_change, which you can set to a Python function or other callable that will be invoked when an event occurs on the target widget.

The example below provides a text input and a button. When you click the button, it opens a dialog displaying the input text:

python

import flet as ft

def main(page: ft.Page):
    page.title = "Flet Event & Callback Demo"
    page.window.width = 340
    page.window.height = 360

    def on_click(e):  # Event handler or callback function
        dialog_text.value = f'You typed: "{txt_input.value}"'
        page.open(dialog)
        page.update()

    txt_input = ft.TextField(label="Type something and press Click Me!")
    btn = ft.ElevatedButton("Click Me!", on_click=on_click)
    dialog_text = ft.Text("")
    dialog = ft.AlertDialog(
        modal=True,
        title=ft.Text("Dialog"),
        content=dialog_text,
        actions=[ft.TextButton("OK", on_click=lambda e: page.close(dialog))],
        open=False,
    )

    page.add(
        txt_input,
        btn,
    )

ft.app(target=main)

When you click the button, the on_click() handler or callback function is automatically called. It sets the dialog's text and opens the dialog. The dialog has an OK button that closes it by calling page.close(dialog).

Run it! You'll get a window like the one shown below.

Flet event handling and callback demo

To see this app in action, type some text into the input and click the Click Me! button.

Conclusion

Flet offers a powerful and modern toolkit for developing GUI applications in Python. It allows you to create desktop and web GUIs from a single codebase. In this tutorial, you've learned the basics of using Flet for desktop apps, including controls, layouts, and event handling.

Now that you understand the fundamentals of Flet, try building your first web app and experimenting with widgets, callbacks, layouts, and more advanced features like theming and navigation.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With NiceGUI for Web UI Development in Python — Your First Steps With the NiceGUI Library for Web UI Development

2025-11-27T06:00:00+00:00

NiceGUI is a Python library that allows developers to create interactive web applications with minimal effort. It's intuitive and easy to use. It provides a high-level interface for building modern web-based graphical user interfaces (GUIs) without requiring deep knowledge of web technologies like HTML, CSS, or JavaScript.

In this tutorial, you'll learn how to use NiceGUI to develop web apps with Python. You'll begin with an introduction to NiceGUI and its capabilities. Then, you'll learn how to create a simple NiceGUI app in Python and explore the basics of the framework's elements. Finally, you'll use NiceGUI to handle events and customize your app's appearance.

To get the most out of this tutorial, you should have a basic knowledge of Python. Familiarity with general GUI programming concepts, such as event handling, widgets, and layouts, will also be beneficial.

Installing NiceGUI

Before using any third-party library like NiceGUI, you must install it in your working environment. Installing NiceGUI is as quick as running the python -m pip install nicegui command in your terminal or command line. This command will install the library from the Python Package Index (PyPI).

It's a good practice to use a Python virtual environment to manage dependencies for your project. To create and activate a virtual environment, open a command line or terminal window and run the following commands in your working directory:

```sh:Windows PS> python -m venv .\venv PS> .\venv\Scripts\activate

python


```sh:macOS
$ python -m venv venv/
$ source venv/bin/activate

```sh:Linux $ python3 -m venv venv/ $ source venv/bin/activate

python


The first command will create a folder called `venv/` containing a Python virtual environment. The Python version in this environment will match the version you have installed on your system.

Once your virtual environment is active, install NiceGUI by running:

```sh
(venv) $ python -m pip install nicegui

With this command, you've installed NiceGUI in your active Python virtual environment and are ready to start building applications.

Writing Your First NiceGUI App in Python

Let's create our first app with NiceGUI and Python. We'll display the traditional "Hello, World!" message in a web browser. To create a minimal NiceGUI app, follow these steps:

Import the ui object from nicegui.
Create a GUI element.
Run the application using the run() method.

Create a Python file named app.py and add the following code:

python

from nicegui import ui

ui.label('Hello, World!').classes('text-h1')

ui.run()

This code defines a web application whose UI consists of a label showing the Hello, World! message. To create the label, we use the ui.label element. The call to ui.run() starts the app.

Run the application by executing the following command in your terminal:

(venv) $ python app.py

This will open your default browser, showing a page like the one below:

First NiceGUI Application

Congratulations! You've just written your first NiceGUI web app using Python. The next step is to explore some features of NiceGUI that will allow you to create fully functional web applications.

If the above command doesn't open the app in your browser, navigate to http://localhost:8080.

Exploring NiceGUI Graphical Elements

NiceGUI elements are the building blocks that we'll arrange to create pages. They represent UI components like buttons, labels, text inputs, and more. The elements are classified into the following categories:

In the following sections, you'll code simple examples showcasing a sample of each category's graphical elements.

Text Elements

NiceGUI has a rich set of text elements that allow you to display text in several ways. This set includes some of the following elements:

The following demo app shows how to create some of these text elements:

python

from nicegui import ui

# Text elements
ui.label("Label")

ui.link("PythonGUIs", "https://pythonguis.com")

ui.chat_message("Hello, World!", name="PythonGUIs Chatbot")

ui.markdown(
    """
# Markdown Heading 1
**bold text**
*italic text*
`code`
"""
)

ui.restructured_text(
    """
==========================
reStructuredText Heading 1
==========================
**bold text**
*italic text*
``code``
"""
)

ui.html("<strong>bold text using HTML tags</strong>")

ui.run(title="NiceGUI Text Elements")

In this example, we create a simple web interface showcasing various NiceGUI text elements. The page shows several text elements, including a basic label, a hyperlink, a chatbot message, and formatted text using the Markdown and reStructuredText markup languages. Finally, it shows some raw HTML.

Each text element allows us to present textual content on the page in a specific way or format, which gives us a lot of flexibility for designing modern web UIs.

Run it! Your browser will open with a page that looks like the following.

Text Elements Demo App in NiceGUI

Control Elements

When it comes to control elements, NiceGUI offers a variety of them. As their name suggests, these elements allow us to control how our web UI behaves. Here are some of the most common control elements available in NiceGUI:

The demo app below showcases some of these NiceGUI control elements:

python

from nicegui import ui

# Control elements
ui.button("Button")

with ui.dropdown_button("Edit", icon="edit", auto_close=True):
    ui.item("Copy")
    ui.item("Paste")
    ui.item("Cut")

ui.toggle(["ON", "OFF"], value="ON")

ui.radio(["NiceGUI", "PyQt6", "PySide6"], value="NiceGUI").props("inline")

ui.checkbox("Enable Feature")

ui.slider(min=0, max=100, value=50, step=5)

ui.switch("Dark Mode")

ui.input("Your Name")

ui.number("Age", min=0, max=120, value=25, step=1)

ui.date(value="2025-04-11")

ui.run(title="NiceGUI Control Elements")

In this app, we include several control elements: a button, a dropdown menu with editing options (Copy, Paste, Cut), and a toggle switch between ON and OFF states. We also have a radio button group to choose between GUI frameworks (NiceGUI, PyQt6, PySide6), a checkbox labeled Enable Feature, and a slider to select a numeric value within a range.

Further down, we have a switch to toggle Dark Mode, a text input field for entering a name, a number input for providing age, and a date picker. Each of these controls has its own properties and methods that you can tweak to customize your web interfaces using Python and NiceGUI.

Note that the elements in this app don't perform any actions. Later in this tutorial, you'll learn about events and actions. For now, we're just showcasing some of the available graphical elements in NiceGUI.

Run it! You'll get a page that will look something like the following.

Control Elements Demo App in NiceGUI

Data Elements

If you're in the data science field, then you'll be thrilled with the variety of data elements that NiceGUI offers. You'll find elements for some of the following tasks:

Representing data in a tabular format
Creating plots and charts
Building different types of progress charts
Displaying 3D objects
Using maps
Creating tree and log views
Presenting and editing text in different formats, including plain text, code, and JSON

Here's a NiceGUI app where we use a table and a Matplotlib plot to present temperature measurements against time:

python

from matplotlib import pyplot as plt
from nicegui import ui

# Data elements
time = [1, 2, 3, 4, 5, 6]
temperature = [30, 32, 34, 32, 33, 31]

columns = [
    {
        "name": "time",
        "label": "Time (min)",
        "field": "time",
        "sortable": True,
        "align": "right",
    },
    {
        "name": "temperature",
        "label": "Temperature (°C)",
        "field": "temperature",
        "required": True,
        "align": "right",
    },
]
rows = [{"time": t, "temperature": temp} for t, temp in zip(time, temperature)]

ui.table(columns=columns, rows=rows, row_key="time")

with ui.pyplot(figsize=(5, 4)):
    plt.plot(time, temperature, "-o", color="blue", label="Temperature")
    plt.title("Temperature vs Time")
    plt.xlabel("Time (min)")
    plt.ylabel("Temperature (°C)")
    plt.ylim(25, 40)
    plt.legend()

ui.run(title="NiceGUI Data Elements")

In this example, we create a web interface that displays a table and a line plot. The data is stored in two lists: one for time (in minutes) and one for temperature (in degrees Celsius). These values are formatted into a table with columns for time and temperature. To render the table, we use the ui.table element.

Below the table, we create a Matplotlib plot of temperature versus time and embed it in the ui.pyplot element. The plot has a title, axis labels, and a legend.

Run it! You'll get a page that looks something like the following.

Data Elements Demo App in NiceGUI

Audiovisual Elements

NiceGUI also has elements that allow us to display audiovisual content in our web UIs. The audiovisual content may include some of the following:

Below is a small demo app that shows how to add a local image to your NiceGUI-based web application:

python

from nicegui import ui

with ui.image("./otje.jpg"):
    ui.label("Otje the cat!").classes("absolute-bottom text-subtitle2 text-center")

ui.run(title="NiceGUI Audiovisual Elements")

In this example, we use the ui.image element to display a local image in your NiceGUI app. The image will show a subtitle at the bottom.

NiceGUI elements provide the classes() method, which allows you to apply Tailwind CSS classes to the target element. To learn more about using CSS for styling your NiceGUI apps, check the Styling & Appearance section in the official documentation.

Run it! You'll get a page that looks something like the following.

Audiovisual Elements Demo App in NiceGUI

Laying Out Pages in NiceGUI

Laying out a GUI so that every graphical component is in the right place is a fundamental step in any GUI project. NiceGUI offers several layout elements that allow us to arrange graphical elements to build a nice-looking UI for our web apps.

Here are some of the most common NiceGUI layout elements:

Cards wrap another element in a frame.
Column arranges elements vertically.
Row arranges elements horizontally.
Grid organizes elements in a grid of rows and columns.
List displays a list of elements.
Tabs organize elements in dedicated tabs.

You'll find several other elements that allow you to tweak how your app's UI looks. Below is a demo app that combines a few of these layout elements to create a minimal but well-organized user profile form:

python

from nicegui import ui

with ui.card().classes("w-full max-w-3xl mx-auto shadow-lg"):
    ui.label("Profile Page").classes("text-xl font-bold")

    with ui.row().classes("w-full"):
        with ui.card():
            ui.image("./profile.png")

            with ui.card_section():
                ui.label("Profile Image").classes("text-center font-bold")
                ui.button("Change Image", icon="photo_camera")

        with ui.card().classes("flex-grow"):
            with ui.column().classes("w-full"):
                ui.input(placeholder="Your Name").classes("w-full")
                ui.select(["Male", "Female", "Other"]).classes("w-full")
                ui.input(placeholder="Eye Color").classes("w-full")
                ui.number(min=0, max=250, value=170, step=1).classes("w-full")
                ui.number(min=0, max=500, value=60, step=0.1).classes("w-full")

            with ui.row().classes("justify-end gap-2 q-mt-lg"):
                ui.button("Reset", icon="refresh").props("outline")
                ui.button("Save", icon="save").props("color=primary")

ui.run(title="NiceGUI Layout Elements")

In this app, we create a clean, responsive profile information page using a layout based on the ui.card element. We center the profile form and cap it at a maximum width for better readability on larger screens.

We organize the elements into two main sections:

A profile image card on the left and a form area on the right. The left section displays a profile picture using the ui.image element with a Change Image button underneath.
A series of input fields for personal information, including the name in a ui.input element, the gender in a ui.select element, the eye color in a ui.input element, and the height and weight in ui.number elements. At the bottom of the form, we add two buttons: Reset and Save.

We use consistent CSS styling throughout the layout to ensure proper spacing, shadows, and responsive controls. This ensures that the interface looks professional and works well across different screen sizes.

Run it! Here's how the form looks in the browser.

A Demo Profile Page Layout in NiceGUI

Handling Events and Actions in NiceGUI

In NiceGUI, you can handle events like mouse clicks, keystrokes, and similar interactions, just as you can in other Python GUI frameworks. Elements typically have arguments like on_click and on_change which are the most direct and convenient way to bind events to actions.

Here's a quick app that shows how to make a NiceGUI app perform actions in response to user events:

python

from nicegui import ui

def on_button_click():
    ui.notify("Button was clicked!")

def on_checkbox_change(event):
    state = "checked" if event.value else "unchecked"
    ui.notify(f"Checkbox is {state}")

def on_slider_change(event):
    ui.notify(f"Slider value: {event.value}")

def on_input_change(event):
    ui.notify(f"Input changed to: {event.value}")

ui.label("Event Handling Demo")

ui.button("Click Me", on_click=on_button_click)
ui.checkbox("Check Me", on_change=on_checkbox_change)
ui.slider(min=0, max=10, value=5, on_change=on_slider_change)
ui.input("Type something", on_change=on_input_change)

ui.run(title="NiceGUI Events & Actions Demo")

In this app, we first define four functions we'll use as actions. When we create the control elements, we use the appropriate argument to bind an event to a function. For example, in the ui.button element, we use the on_click argument, which makes the button call the associated function when we click it.

We do something similar with the other elements, but use different arguments depending on the element's supported events.

You can check the NiceGUI documentation for individual elements to learn about the specific events they can handle.

Using the on_* type of arguments is not the only way to bind events to actions in NiceGUI. You can also use the on() method, which allows you to attach event handlers manually. This approach is handy for less common events or when you want to attach multiple handlers to a single element.

Here's a quick example:

python

from nicegui import ui

def on_click(event):
    ui.notify("Button was clicked!")

def on_hover(event):
    ui.notify("Button was hovered!")

button = ui.button("Button")
button.on("click", on_click)
button.on("mouseover", on_hover)

ui.run()

In this example, we create a small web app with a single button that responds to two different events. When you click the button, the on_click() function triggers a notification. Similarly, when you hover the mouse over the button, the on_hover() function displays a notification.

To bind the events to the corresponding function, we use the on() method. The first argument is a string representing the name of the target event. The second argument is the function that we want to run when the event occurs.

Conclusion

In this tutorial, you've learned the basics of creating web applications with NiceGUI, a powerful Python library for building browser-based user interfaces.

You've explored common NiceGUI elements including text, controls, data, and audiovisual components. You've also learned how to arrange elements using layouts like cards, rows, and columns, and how to handle user events to make your apps interactive. This gives you the foundation to build modern and interactive web interfaces entirely in Python. For further exploration and advanced features, refer to the official NiceGUI documentation.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With DearPyGui for GUI Development — Your First Steps With the DearPyGui Library for Desktop Python GUIs

2025-11-19T08:00:00+00:00

Getting started with a new GUI framework can feel daunting. This guide walks you through the essentials of DearPyGui—from installation and your first app to widgets, layouts, event handling, and plotting.

With DearPyGui, you can quickly build modern, high‑performance desktop interfaces using Python.

What Is DearPyGui?

DearPyGui is a GPU‑accelerated and cross‑platform GUI framework for Python, built on Dear ImGui with a retained‑mode Python API. It renders all UI using the GPU rather than native OS widgets, ensuring consistent, high‑performance UI across Windows, Linux, macOS, and even Raspberry Pi 4.

Note that official wheels for Raspberry Pi may lag behind. Users sometimes compile from source.

DearPyGui's key features include the following:

Modern, consistent UI across platforms
High performance via GPU rendering and C/C++ core
Customizable styles/themes and full developer tools
Over 70 widgets, including plots, node editors, and tables
Built-in demo app, theme inspector, logging, metrics, and debugger

This Python GUI framework is ideal for building interfaces ranging from simple utilities to real-time dashboards, data‑science tools, or interactive applications.

Installing DearPyGui

You can install DearPyGui from PyPI using pip:

$ pip install dearpygui

This command installs DearPyGui from PyPI.

Writing Your First DearPyGui Application

In general, DearPyGui apps follow the following structure:

dpg.create_context() — Initialize DearPyGui and call it before anything else
dpg.create_viewport() — Create the main application window or viewport
Define UI widgets within windows or groups — Add and configure widgets and containers to build your interface
dpg.setup_dearpygui() — Set up DearPyGui internals and resources before showing the viewport
dpg.show_viewport() — Make the viewport window visible to the user
dpg.start_dearpygui() — Start the DearPyGui main event and render loop
dpg.destroy_context() — Clean up and release all DearPyGui resources on exit

Here's a quick Hello World application displaying a window with basic widgets:

python

import dearpygui.dearpygui as dpg

def main():
    dpg.create_context()
    dpg.create_viewport(title="Viewport", width=300, height=100)

    with dpg.window(label="DearPyGui Demo", width=300, height=100):
        dpg.add_text("Hello, World!")

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

Inside main(), we initialize the library with dpg.create_context(), create a window (viewport) via dpg.create_viewport(), define the GUI, set up the library with dpg.setup_dearpygui(), show the viewport with dpg.show_viewport(), and run the render loop using dpg.start_dearpygui(). When you close the window, dpg.destroy_context() cleans up resources.

You define the GUI itself inside a dpg.window() context block, which parents a text item with the label "Hello, World!".

Always follow the lifecycle order: create context → viewport → setup → show → start → destroy. Otherwise, the app may crash.

Run it! Here's what your first DearPyGui app looks like.

DearPyGui first app

Exploring DearPyGui Widgets

DearPyGui includes a wide variety of widgets for building Python GUIs:

Basic widgets, including buttons, text input, sliders, and checkboxes
Containers like windows, groups (horizontal and vertical grouping), tabs, collapsing headers, and menus
Interactive widgets, such as color pickers, combo boxes, tables, and menus

Here's an example that showcases some commonly used DearPyGui widgets:

python

import dearpygui.dearpygui as dpg

def main():
    dpg.create_context()
    dpg.create_viewport(title="Widgets Demo", width=400, height=450)

    with dpg.window(
        label="Common DearPyGui Widgets",
        width=380,
        height=420,
        pos=(10, 10),
    ):
        dpg.add_text("Static label")
        dpg.add_input_text(
            label="Text Input",
            default_value="Type some text here...",
            tag="widget_input",
        )
        dpg.add_button(label="Click Me!")
        dpg.add_checkbox(label="Check Me!")
        dpg.add_radio_button(
            ("DearPyGui", "PyQt6", "PySide6"),
        )

        dpg.add_slider_int(
            label="Int Slider",
            default_value=5,
            min_value=0,
            max_value=10,
        )
        dpg.add_slider_float(
            label="Float Slider",
            default_value=0.5,
            min_value=0.0,
            max_value=1.0,
        )

        dpg.add_combo(
            ("DearPyGui", "PyQt6", "PySide6"),
            label="GUI Library",
        )
        dpg.add_color_picker(label="Pick a Color")
        dpg.add_progress_bar(
            label="Progress",
            default_value=0.5,
            width=250,
        )

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

This code uses the following functions to add the widgets to the GUI:

add_text(): A label for static text or instructions
add_input_text(): A single‑line text entry field
add_button(): A clickable button for user actions
add_checkbox(): A toggle for boolean values
add_radio_button(): A group of radio buttons for selecting one from several options
add_slider_int(), add_slider_float(): Sliders with integer and floating-point steps
add_combo(): A dropdown selection widget
add_color_picker(): A color picker widget
add_progress_bar(): A progress bar widget to display visual progress

Run it! Here's what the app will look like.

DearPyGui basic widgets

Laying Out Your DearPyGui Interface

By default, DearPyGui stacks widgets vertically. However, additional positioning options include the following:

Horizontal grouping using with dpg.group(horizontal=True):
Vertical spacing using dpg.add_spacer()
Indentation using the per-item indent keyword argument, like in dpg.add_checkbox(label="Option A", indent=30) or after creation with dpg.configure_item(tag, indent=30)
Absolute positioning via pos=(x, y) when creating items, or with dpg.set_item_pos(tag, (x, y)) after creation

Widgets go inside containers like dpg.window(). You can nest containers to build complex GUI layouts:

python

import dearpygui.dearpygui as dpg

def main():
    dpg.create_context()
    dpg.create_viewport(title="Layout Demo", width=520, height=420)

    with dpg.window(
        label="Layout Demo",
        width=500,
        height=380,
        pos=(10, 10),
    ):
        dpg.add_text("1) Vertical layout:")
        dpg.add_button(label="Top")
        dpg.add_button(label="Middle")
        dpg.add_button(label="Bottom")

        dpg.add_spacer(height=12)

        dpg.add_text("2) Horizontal layout:")
        with dpg.group(horizontal=True):
            dpg.add_button(label="Left")
            dpg.add_button(label="Center")
            dpg.add_button(label="Right")

        dpg.add_spacer(height=12)

        dpg.add_text("3) Indentation:")
        dpg.add_checkbox(label="Indented at creation (30px)", indent=30)
        dpg.add_checkbox(label="Indented after creation (35px)", tag="indent_b")
        dpg.configure_item("indent_b", indent=35)

        dpg.add_spacer(height=12)

        dpg.add_text("4) Absolute positioning:")
        dpg.add_text("Positioned at creation: (x=100, y=300)", pos=(100, 300))
        dpg.add_text("Positioned after creation: (x=100, y=320)", tag="move_me")
        dpg.set_item_pos("move_me", (100, 320))

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

In this example, we create an app that showcases basic layout options in DearPyGui. The first section of widgets shows the default vertical stacking by adding three buttons one after another. Then, you use dpg.add_spacer(height=12) to insert vertical whitespace between sections.

Then, we create a horizontal row of buttons with dpg.group(horizontal=True), which groups items side-by-side. Next, we have an indentation section that demonstrates how to indent widgets at creation (indent=30) and after creation using dpg.configure_item().

Finally, we use absolute positioning by placing one text item at a fixed coordinate using pos=(100, 300) and moving another after creation with dpg.set_item_pos(). These patterns are all part of DearPyGui's container and item-configuration model, which we can use to arrange the widgets in a user-friendly GUI.

Run it! You'll get a window like the following.

DearPyGui layouts

Handling Events with DearPyGui Callbacks

DearPyGui uses callbacks to handle events. Most widgets accept a callback argument, which is executed when we interact with the widget itself.

The example below provides a text input and a button. When we click the button, it opens a dialog showing the input text:

python

import dearpygui.dearpygui as dpg

def on_click_callback(sender, app_data, user_data):
    text = dpg.get_value("input_text")
    dpg.set_value("dialog_text", f'You typed: "{text}"')
    dpg.configure_item("dialog", show=True)

def main() -> None:
    dpg.create_context()
    dpg.create_viewport(title="Callback Example", width=270, height=120)

    with dpg.window(label="Callback Example", width=250, height=80, pos=(10, 10)):
        dpg.add_text("Type something and press Click Me!")
        dpg.add_input_text(label="Input", tag="input_text")
        dpg.add_button(label="Click Me!", callback=on_click_callback)
        with dpg.window(
            label="Dialog",
            modal=True,
            show=False,
            width=230,
            height=80,
            tag="dialog",
            no_close=True,
            pos=(10, 10),
        ):
            dpg.add_text("", tag="dialog_text")
            dpg.add_button(
                label="OK",
                callback=lambda s, a, u: dpg.configure_item("dialog", show=False),
            )

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

The button takes the on_click_callback() callback as an argument. When we click the button, DearPyGui invokes the callback with three standard arguments:

sender, which holds the button's ID
app_data, which holds extra data specific to certain widgets
user_data, which holds custom data you could have supplied

Inside the callback, we pull the current text from the input widget using dpg.get_value(), and finally, we display the input text in a modal window.

Run it! You'll get a window like the following.

DearPyGui callbacks

To see this app in action, type some text into the input and click the Click Me! button.

Creating Plots and Charts with DearPyGui

DearPyGui comes with powerful plotting capabilities built in. It includes high-performance plots such as lines, bars, scatter plots, and histograms. These plots allow interactive zoom and pan and real-time data updates, making them excellent for scientific visualizations and data dashboards.

Here's an example of how to create a line plot using DearPyGui's plotting widgets:

python

import dearpygui.dearpygui as dpg
import numpy as np

def main() -> None:
    dpg.create_context()
    dpg.create_viewport(title="Plotting Example", width=420, height=320)

    x = np.linspace(0, 2 * np.pi, 100)
    y1 = np.sin(x)
    y2 = np.cos(x)

    with dpg.window(label="Plot Window", width=400, height=280, pos=(10, 10)):
        with dpg.plot(label="Sine and Cosine Plot", height=200, width=360):
            dpg.add_plot_legend()
            dpg.add_plot_axis(dpg.mvXAxis, label="X")
            with dpg.plot_axis(dpg.mvYAxis, label="Y"):
                dpg.add_line_series(x.tolist(), y1.tolist(), label="sin(x)")
                dpg.add_line_series(x.tolist(), y2.tolist(), label="cos(x)")

    dpg.setup_dearpygui()
    dpg.show_viewport()
    dpg.start_dearpygui()
    dpg.destroy_context()

if __name__ == "__main__":
    main()

In this example, we create two line series: sine and cosine curves. To plot them, we use NumPy‑generated data. We also add X and Y axes, plus a legend for clarity. You can update the series in a callback for live data dashboards.

Run it! You'll get a plot like the one shown below.

DearPyGui plotting demo

Conclusion

DearPyGui offers a powerful and highly customizable GUI toolkit for building desktop applications in Python. With a rich widget set, interactive plotting, node editors, and built-in developer tools, it's a great choice for both simple utilities and complex interfaces.

In this tutorial, you learned how to install DearPyGui, create your first application, work with widgets and layouts, handle events with callbacks, and create interactive plots. Try building your own DearPyGui app and experimenting with these features to create professional Python desktop GUIs!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Saving and Restoring Application Settings with QSettings in PyQt6 — Learn how to use QSettings to remember user preferences, window sizes, and configuration options between sessions

2025-10-09T09:00:00+00:00

Most desktop applications need to remember things between sessions. Maybe your user picked a dark theme, resized the window, or toggled a feature on or off. Without a way to save those choices, your app would forget everything the moment it closes. That's where QSettings comes in.

QSettings is a class provided by Qt (and available through PyQt6) that gives you a simple, cross-platform way to store and retrieve application settings. It handles all the platform-specific details for you — on Windows it uses the registry, on macOS it uses property list files, and on Linux it uses configuration files. You just read and write values, and Qt figures out the rest.

In this tutorial, we'll walk through everything you need to know to start using QSettings effectively in your PyQt6 applications.

Creating a QSettings Object

To use QSettings, you first need to create an instance. The most common way is to pass in your organization name and application name:

python

from PyQt6.QtCore import QSettings

settings = QSettings('MyCompany', 'MyApp')

These two strings — the organization name and the application name — are used by Qt to determine where your settings are stored. They act like a namespace, keeping your app's settings separate from every other application on the system.

You can check exactly where your settings file lives by printing the file path:

python

print(settings.fileName())

On Linux, this might print something like:

python

/home/username/.config/MyCompany/MyApp.conf

On Windows, it would point to a registry path, and on macOS, a .plist file. You don't need to worry about these differences — QSettings handles it for you.

Storing Values

Saving a setting is as simple as calling setValue() with a key and a value:

python

settings.setValue('theme', 'Dark')
settings.setValue('font_size', 14)
settings.setValue('show_toolbar', True)

The key is a string that you'll use later to retrieve the value. The value can be a string, integer, boolean, list, or other common Python types. QSettings will serialize it appropriately.

That's it — the value is saved. When you call setValue(), the data is written to persistent storage (the exact timing depends on the platform, but it happens automatically).

Reading Values Back

To read a setting, use value():

python

theme = settings.value('theme')
print(theme)  # 'Dark'

If the key doesn't exist (for example, the very first time your app runs), value() returns None by default. You can provide a default value as the second argument:

python

theme = settings.value('theme', 'Light')

Now if there's no theme key stored yet, you'll get 'Light' instead of None.

Handling Types

One thing that catches people off guard: QSettings stores everything as strings internally (at least when using INI-style backends on Linux). This means that when you read back a number or boolean, you might get a string instead of the type you expected.

To handle this, you can pass the type parameter:

python

font_size = settings.value('font_size', 14, type=int)
show_toolbar = settings.value('show_toolbar', True, type=bool)

By specifying type=int or type=bool, you ensure that the returned value is the correct Python type, regardless of how it was stored internally. This is especially important for booleans — without the type parameter, you might get the string 'true' instead of the boolean True.

Checking if a Setting Exists

Before reading a value, you might want to check whether it has been set at all. Use contains():

python

if settings.contains('theme'):
    theme = settings.value('theme')
    print(f'Found saved theme: {theme}')
else:
    print('No theme saved yet, using default')
    settings.setValue('theme', 'Light')
    theme = 'Light'

This pattern is useful when you want to distinguish between "the user explicitly set this value" and "this is just the default."

A Complete Example

Let's put this all together in a small PyQt6 application that remembers the window size and position, as well as a user-selected theme. When you close the app, it saves these settings. When you reopen it, everything is restored.

python

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QComboBox,
    QVBoxLayout, QWidget, QLabel
)
from PyQt6.QtCore import QSettings, QSize, QPoint


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.settings = QSettings('MyCompany', 'MyApp')

        self.setWindowTitle("QSettings Demo")

        # Create a simple UI with a theme selector
        layout = QVBoxLayout()

        layout.addWidget(QLabel("Choose a theme:"))

        self.theme_combo = QComboBox()
        self.theme_combo.addItems(['Light', 'Dark', 'Blue'])
        layout.addWidget(self.theme_combo)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

        # Restore settings
        self.load_settings()

    def load_settings(self):
        # Restore window size and position
        size = self.settings.value('window_size', QSize(400, 300))
        position = self.settings.value('window_position', QPoint(100, 100))
        self.resize(size)
        self.move(position)

        # Restore theme selection
        theme = self.settings.value('theme', 'Light')
        index = self.theme_combo.findText(theme)
        if index >= 0:
            self.theme_combo.setCurrentIndex(index)

    def save_settings(self):
        self.settings.setValue('window_size', self.size())
        self.settings.setValue('window_position', self.pos())
        self.settings.setValue('theme', self.theme_combo.currentText())

    def closeEvent(self, event):
        self.save_settings()
        super().closeEvent(event)


app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Run this app, move or resize the window, select a different theme from the dropdown, then close the app. When you run it again, the window should appear in the same position and size, with the same theme selected.

Let's walk through what's happening:

In __init__, we create a QSettings object with our organization and app names.
load_settings() reads values from persistent storage and applies them to the window and widgets. Notice how we pass default values (QSize(400, 300), QPoint(100, 100), 'Light') so the app has sensible starting values on the very first run.
save_settings() writes the current window size, position, and theme to settings.
closeEvent() is a built-in Qt method that gets called when the window is about to close. We override it to save our settings right before that happens.

If you're looking for a more robust approach to saving and restoring window geometry — including handling multiple monitors and window states — take a look at our dedicated guide on restoring window geometry with PyQt.

Removing Settings

If you need to delete a stored setting, use remove():

python

settings.remove('theme')

This removes the theme key entirely. After this, settings.contains('theme') would return False.

Listing All Keys

To see everything that's currently stored, use allKeys():

python

keys = settings.allKeys()
print(keys)  # ['theme', 'font_size', 'show_toolbar', ...]

This can be handy for debugging, or if you want to iterate over all settings to display them in a preferences dialog.

Organizing Settings with Groups

As your app grows, you might end up with a lot of settings. QSettings supports groups, which let you organize keys into sections — similar to folders:

python

settings.beginGroup('appearance')
settings.setValue('theme', 'Dark')
settings.setValue('font_size', 14)
settings.endGroup()

settings.beginGroup('network')
settings.setValue('timeout', 30)
settings.setValue('retry_count', 3)
settings.endGroup()

When you read them back, you use the same group:

python

settings.beginGroup('appearance')
theme = settings.value('theme', 'Light')
settings.endGroup()

Alternatively, you can use a / separator in the key name as a shorthand:

python

settings.setValue('appearance/theme', 'Dark')
theme = settings.value('appearance/theme', 'Light')

Both approaches produce the same result. The slash syntax is a bit more concise, while beginGroup()/endGroup() is cleaner when you're reading or writing several settings in the same group at once.

Using QSettings with setOrganizationName and setApplicationName

Instead of passing the organization and app names every time you create a QSettings object, you can set them once on the QApplication:

python

app = QApplication(sys.argv)
app.setOrganizationName('MyCompany')
app.setApplicationName('MyApp')

After this, you can create QSettings objects without any arguments:

python

settings = QSettings()

It will automatically use the organization and application names you set. This is especially convenient in larger applications where you create QSettings in multiple places — you only need to define the names once at startup. If you're new to building PyQt6 applications and want to understand how QApplication and windows work, see our tutorial on creating your first window in PyQt6.

Managing Many Settings with a Dictionary

If your application has a lot of settings, checking each one individually can get repetitive. A cleaner approach is to define your defaults in a dictionary and loop through them:

python

DEFAULTS = {
    'theme': 'Light',
    'font_size': 14,
    'show_toolbar': True,
    'language': 'English',
    'auto_save': True,
    'auto_save_interval': 5,
}

settings = QSettings('MyCompany', 'MyApp')

# Load settings with defaults
config = {}
for key, default in DEFAULTS.items():
    config[key] = settings.value(key, default, type=type(default))

print(config)

By using type=type(default), each value is automatically cast to the same type as its default. This keeps everything tidy and makes it easy to add new settings later — just add another entry to the dictionary.

Where Are Settings Stored?

If you're curious about where QSettings puts your data, or if you need to find the settings file for debugging, here's a quick summary:

Platform	Storage Location
Windows	Registry under `HKEY_CURRENT_USER\Software\MyCompany\MyApp`
macOS	`~/Library/Preferences/com.mycompany.MyApp.plist`
Linux	`~/.config/MyCompany/MyApp.conf`

You can always check the exact path using:

python

print(settings.fileName())

On Linux and macOS, the settings file is a plain text file that you can open and inspect directly, which is helpful for debugging.

Working with QStandardPaths

QSettings tells you where settings are stored, but sometimes you need to know about other standard locations — where to store cached data, application data, or downloaded files. Qt provides QStandardPaths for this:

python

from PyQt6.QtCore import QStandardPaths

# Where to store app configuration
config_path = QStandardPaths.writableLocation(QStandardPaths.AppConfigLocation)
print(f'Config: {config_path}')

# Where to store app data
data_path = QStandardPaths.writableLocation(QStandardPaths.AppDataLocation)
print(f'Data: {data_path}')

# Where to store cached files
cache_path = QStandardPaths.writableLocation(QStandardPaths.CacheLocation)
print(f'Cache: {cache_path}')

QStandardPaths is separate from QSettings, but they complement each other well. Use QSettings for simple key-value preferences, and QStandardPaths when you need to store actual files (databases, logs, downloaded content) in the right platform-appropriate location.

Summary

QSettings gives you a clean, cross-platform way to persist user preferences in your PyQt6 applications. Here's a quick recap of the essentials:

Create a QSettings object with your organization and app name.
Use setValue(key, value) to save a setting.
Use value(key, default, type=...) to read a setting, with a default fallback and explicit type.
Use contains(key) to check if a setting exists.
Use remove(key) to delete a setting.
Override closeEvent() on your main window to save settings when the app closes.
Organize related settings with groups using beginGroup()/endGroup() or / in key names.

Once you're comfortable with these basics, you'll find that QSettings quietly handles one of those essential-but-tedious parts of desktop app development — letting you focus on the interesting stuff. When you're ready to distribute your finished application, check out our guide on packaging PyQt6 applications with PyInstaller on Windows to ship your app with all its settings support intact.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

How can I enable editing on a QTableView in PySide6? — Modifying your model to allow editing of your data source

2025-08-19T06:00:00+00:00

In the Model-Views course, we covered Displaying Tabular Data in Qt ModelViews. This takes a data source, such as a list of lists, a NumPy array, or a Pandas DataFrame, and displays it in a QTableView. But often, displaying is just the first step—you also want your users to be able to add and edit the table, updating the underlying data object.

Reader Vic T asked:

I have been trying for a few days to get edit mode to work with a QTableView using Pandas for the model via QAbstractTableModel. Having searched all over the internet although, I found suggestions to implement the flags() method, but it doesn't seem to work.

This is a common question when building editable tables in PySide6. The answer involves three key methods on your QAbstractTableModel: flags(), setData(), and an update to data(). Let's walk through each one.

Implement `flags()` to Enable Editing on QTableView

You need to implement the flags() method on your model to inform Qt that your model supports editing. To do this, your method needs to return the Qt.ItemFlag.ItemIsEditable flag, which you or together (using the pipe | character) with the other flags.

For example:

python

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

Implement `setData()` to Handle User Edits

However, to get the editing working, you also need to implement a setData() method. This method is the model's interface between Qt and your data object. It takes care of making the changes to the data.

Remember, Qt views don't know anything about your data beyond what you tell them via the model. Likewise, they also don't know how to update your list, NumPy array, or DataFrame objects with the new data that has been provided. You need to handle that yourself!

Below are some example setData() methods for lists of lists, NumPy, and Pandas. The only difference is how we index into the data object:

List
Pandas
NumPy

python
    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data[index.row()][index.column()] = value
            return True

python
    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data.iloc[index.row(),index.column()] = value
            return True

python
    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data[index.row(), index.column()] = value
            return True

Notice that we first need to check whether the role is Qt.ItemDataRole.EditRole to determine if an edit is currently being made. After making the edit, we return True to confirm this.

Update `data()` to Show Current Values When Editing

If you try the above on your model, you should be able to edit the values. However, you'll notice that when editing, it clears the current value of the cell — you have to start from an empty cell. To display the current value when editing, you need to modify the data() method to return the current value when the role is Qt.ItemDataRole.EditRole as well as when it is Qt.ItemDataRole.DisplayRole.

For example:

List
Pandas
NumPy

python
    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row()][index.column()]
                return str(value)

python
    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data.iloc[index.row(), index.column()]
                return str(value)

python
    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row(), index.column()]
                return str(value)

That's it, you should now have a properly editable QTableView in PySide6.

Complete Editable QTableView Examples in PySide6

Below are complete working examples for list, NumPy, and Pandas data sources with PySide6. You can copy and run these directly to see editable table views in action.

Editable QTableView with a Python List of Lists

The following example uses a nested Python list of lists as a data source for an editable QTableView with QAbstractTableModel:

python

from PySide6.QtCore import QAbstractTableModel, Qt
from PySide6.QtWidgets import QApplication, QMainWindow, QTableView

class ListModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, index):
        return len(self._data)

    def columnCount(self, index):
        # The following takes the first sub-list, and returns
        # the length (only works if all rows are an equal length)
        return len(self._data[0])

    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row()][index.column()]
                return str(value)

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data[index.row()][index.column()] = value
            return True
        return False

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.table = QTableView()

        data = [
            [1, 9, 2],
            [1, 0, -1],
            [3, 5, 2],
            [3, 3, 2],
            [5, 8, 9],
        ]

        self.model = ListModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)

app = QApplication([])
window = MainWindow()
window.show()
app.exec_()

Editable QTableView with a Pandas DataFrame

The following example uses a Pandas DataFrame as the data source for an editable QTableView, including column headings from the DataFrame column names:

python

import pandas as pd
from PySide6.QtCore import QAbstractTableModel, Qt
from PySide6.QtWidgets import QApplication, QMainWindow, QTableView

class PandasModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, index):
        return self._data.shape[0]

    def columnCount(self, parent=None):
        return self._data.shape[1]

    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data.iloc[index.row(), index.column()]
                return str(value)

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data.iloc[index.row(), index.column()] = value
            return True
        return False

    def headerData(self, col, orientation, role):
        if (
            orientation == Qt.Orientation.Horizontal
            and role == Qt.ItemDataRole.DisplayRole
        ):
            return self._data.columns[col]

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.table = QTableView()

        data = pd.DataFrame(
            [
                [1, 9, 2],
                [1, 0, -1],
                [3, 5, 2],
                [3, 3, 2],
                [5, 8, 9],
            ],
            columns=["A", "B", "C"],
        )

        self.model = PandasModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)

app = QApplication([])
window = MainWindow()
window.show()
app.exec_()

Editable QTableView with a NumPy Array

The following example uses a NumPy array as the data source for an editable QTableView. The array will only accept valid values (in this case, integers) when setting, so we must first coerce the value to an integer before setting it on the array. If you enter something which isn't a valid integer (e.g. jdskfjdskjfndsf ), the int() call will throw a ValueError, which we catch. By returning False when this exception is thrown, we cancel the edit:

python

import numpy as np
from PySide6.QtCore import QAbstractTableModel, Qt
from PySide6.QtWidgets import QApplication, QMainWindow, QTableView

class NumPyModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, index):
        return self._data.shape[0]

    def columnCount(self, index):
        return self._data.shape[1]

    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row(), index.column()]
                return str(value)

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            try:
                value = int(value)
            except ValueError:
                return False
            self._data[index.row(), index.column()] = value
            return True
        return False

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.table = QTableView()

        data = np.array(
            [
                [1, 9, 2],
                [1, 0, -1],
                [3, 5, 2],
                [3, 3, 2],
                [5, 8, 9],
            ]
        )

        self.model = NumPyModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)

app = QApplication([])
window = MainWindow()
window.show()
app.exec()

Summary

To make a QTableView editable in PySide6, you need to implement three things on your QAbstractTableModel:

flags() — Return Qt.ItemFlag.ItemIsEditable to enable cell editing.
setData() — Handle writing the new value back to your data source (list, Pandas DataFrame, or NumPy array).
data() with EditRole — Return the current cell value for both DisplayRole and EditRole so the editor is pre-populated.

With these three methods in place, your QTableView will support full inline editing of table data, regardless of the underlying data structure you're using.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

How can I enable editing on a QTableView in PyQt6? — Modifying your model to allow editing of your data source

2025-07-19T06:00:00+00:00

Reader Vic T asked:

I have been trying for a few days to get edit mode to work with a QTableView using Pandas for the model via QAbstractTableModel. Having searched all over the internet although, I found suggestions to implement the flags() method, but it doesn't seem to work.

This is correct. You need to implement the flags() method on your model to inform Qt that your model supports editing. To do this, your method needs to return the Qt.ItemFlag.ItemIsEditable flag, which you or together (using the pipe | character) with the other flags.

In this guide, you'll learn the three steps required to make a QTableView editable in PyQt6: implementing flags(), setData(), and updating data(). We'll cover complete working examples using Python lists, Pandas DataFrames, and NumPy arrays.

Implement `flags()` to enable editing on QTableView

The first step to making your QTableView editable is to return the ItemIsEditable flag from your model's flags() method. Without this flag, double-clicking a cell in the table view won't open an editor widget:

python

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

Implement `setData()` to write changes to the data source

Below are some example setData() methods for lists of lists, NumPy, and Pandas. The only difference between each implementation is how we index into the data object:

List
Pandas
NumPy

python
    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data[index.row()][index.column()] = value
            return True

python
    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data.iloc[index.row(),index.column()] = value
            return True

python
    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data[index.row(), index.column()] = value
            return True

Notice that we first need to check whether the role is Qt.ItemDataRole.EditRole to determine if an edit is currently being made. After making the edit, we return True to confirm the data was set successfully.

Update `data()` to show the current value when editing

For example:

List
Pandas
NumPy

python
    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row()][index.column()]
                return str(value)

python
    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data.iloc[index.row(), index.column()]
                return str(value)

python
    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row(), index.column()]
                return str(value)

That's it! You should now have a properly editable QTableView in PyQt6.

Below are complete working examples for each data source type: Python lists, Pandas DataFrames, and NumPy arrays.

Editable QTableView with a Python list of lists

The following example uses a nested Python list of lists as a data source for an editable QTableView. This is the simplest approach and doesn't require any external libraries:

python

from PyQt6.QtCore import QAbstractTableModel, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView

class ListModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, index):
        return len(self._data)

    def columnCount(self, index):
        # The following takes the first sub-list, and returns
        # the length (only works if all rows are an equal length)
        return len(self._data[0])

    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row()][index.column()]
                return str(value)

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data[index.row()][index.column()] = value
            return True
        return False

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.table = QTableView()

        data = [
            [1, 9, 2],
            [1, 0, -1],
            [3, 5, 2],
            [3, 3, 2],
            [5, 8, 9],
        ]

        self.model = ListModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)

app = QApplication([])
window = MainWindow()
window.show()
app.exec()

Editable QTableView with a Pandas DataFrame

The following example uses a Pandas DataFrame as the data source for an editable QTableView, adding column headings from the DataFrame column names:

python

import pandas as pd
from PyQt6.QtCore import QAbstractTableModel, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView

class PandasModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, index):
        return self._data.shape[0]

    def columnCount(self, parent=None):
        return self._data.shape[1]

    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data.iloc[index.row(), index.column()]
                return str(value)

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            self._data.iloc[index.row(), index.column()] = value
            return True
        return False

    def headerData(self, col, orientation, role):
        if (
            orientation == Qt.Orientation.Horizontal
            and role == Qt.ItemDataRole.DisplayRole
        ):
            return self._data.columns[col]

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.table = QTableView()

        data = pd.DataFrame(
            [
                [1, 9, 2],
                [1, 0, -1],
                [3, 5, 2],
                [3, 3, 2],
                [5, 8, 9],
            ],
            columns=["A", "B", "C"],
        )

        self.model = PandasModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)

app = QApplication([])
window = MainWindow()
window.show()
app.exec()

Editable QTableView with a NumPy array

The following example uses a NumPy array as the data source for an editable QTableView. Because the array will only accept valid values (in this case, integers) when setting, we must first coerce the value to an integer before setting it on the array. If you enter something which isn't a valid integer (e.g. jdskfjdskjfndsf ), the int() call will throw a ValueError, which we catch. By returning False when this exception is thrown, we cancel the edit:

python

import numpy as np
from PyQt6.QtCore import QAbstractTableModel, Qt
from PyQt6.QtWidgets import QApplication, QMainWindow, QTableView

class NumPyModel(QAbstractTableModel):
    def __init__(self, data):
        super().__init__()
        self._data = data

    def rowCount(self, index):
        return self._data.shape[0]

    def columnCount(self, index):
        return self._data.shape[1]

    def data(self, index, role=Qt.ItemDataRole.DisplayRole):
        if index.isValid():
            if role == Qt.ItemDataRole.DisplayRole or role == Qt.ItemDataRole.EditRole:
                value = self._data[index.row(), index.column()]
                return str(value)

    def setData(self, index, value, role):
        if role == Qt.ItemDataRole.EditRole:
            try:
                value = int(value)
            except ValueError:
                return False
            self._data[index.row(), index.column()] = value
            return True
        return False

    def flags(self, index):
        return (
            Qt.ItemFlag.ItemIsSelectable
            | Qt.ItemFlag.ItemIsEnabled
            | Qt.ItemFlag.ItemIsEditable
        )

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.table = QTableView()

        data = np.array(
            [
                [1, 9, 2],
                [1, 0, -1],
                [3, 5, 2],
                [3, 3, 2],
                [5, 8, 9],
            ]
        )

        self.model = NumPyModel(data)
        self.table.setModel(self.model)

        self.setCentralWidget(self.table)

app = QApplication([])
window = MainWindow()
window.show()
app.exec()

Summary

To make a QTableView editable in PyQt6 using QAbstractTableModel, you need to implement three things:

flags() — Return Qt.ItemFlag.ItemIsEditable to enable editing on cells.
setData() — Handle writing the new value back to your data source (list, Pandas DataFrame, or NumPy array).
data() with EditRole — Return the current cell value for EditRole so the editor is pre-populated.

These same principles apply whether you're using PyQt6, PyQt5, or PySide6 — only the enum paths differ slightly between frameworks.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

6th Edition - Create GUI Applications with Python & Qt, Released — PyQt6 & PySide6 books updated for 2025 with model view controller architecture, new Python/Qt features and more examples

2025-06-11T08:00:00+00:00

The 6th edition of my book Create GUI Applications with Python & Qt is now available for both PyQt6 and PySide6.

PyQt6 — Create GUI Applications with Python & Qt6 / PyQt6 Book, 6th Edition
PySide6 — Create GUI Applications with Python & Qt6 / PySide6 Book, 6th Edition

This update brings the book up to date with the latest changes in PyQt6 & PySide6, and also updates code to make use of newer features in Python. Many of the chapters have been updated and extended with more examples of form layouts, built-in dialogs and architecture, particularly using Model View Controller (MVC) architecture.

What's new in the 6th edition?

Updated for PyQt6 & PySide6 with the latest Qt6 API changes
Expanded coverage of Model View Controller (MVC) architecture for Python GUI apps
More examples of form layouts, built-in dialogs, and application architecture
Code updated to leverage modern Python 3 features and best practices
Additional real-world examples to help you build professional desktop applications

Buy the latest edition

PyQt6 — PyQt6 Book, 6th Edition, Create GUI Applications with Python & Qt6
PySide6 — PySide6 Book, 6th Edition, Create GUI Applications with Python & Qt6

Free updates for existing readers

As always, if you've previously bought a copy of the book you get these updates for free! Just go to your account downloads page and enter the email you used for the purchase.

If you bought the book elsewhere (in paperback or digital) you can register to get these updates too — just email your receipt to register@pythonguis.com

Enjoy!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Tkinter Widgets — A walkthrough of Tkinter's basic widgets

2025-05-19T06:00:00+00:00

In Tkinter (and most GUI libraries), widget is the name given to a component of the GUI that the user can interact with. User interfaces are made up of multiple widgets arranged within the window to make it functional and intuitive to use.

Tkinter comes with a decent set of widgets and even allows you to create your own custom widgets or customize existing ones.

A Quick Demo

First, let's have a look at some of the most common Tkinter widgets. The following code creates a range of Tkinter widgets and adds them to a window layout so you can see them together:

python

import tkinter as tk
from tkinter import ttk

root = tk.Tk()
root.title("Widgets Demo")

widgets = [
    tk.Label,
    tk.Checkbutton,
    ttk.Combobox,
    tk.Entry,
    tk.Button,
    tk.Radiobutton,
    tk.Scale,
    tk.Spinbox,
]

for widget in widgets:
    try:
        widget = widget(root, text=widget.__name__)
    except tk.TclError:
        widget = widget(root)
    widget.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Widgets Demo on macOS

You can learn how the pack() geometry manager works in our Using the Pack Geometry Manager in Tkinter tutorial.

Let's have a look at all the example widgets, from top to bottom:

Widget	Description
`Label`	Just a label, not interactive
`Checkbutton`	A checkbox
`Combobox`	A dropdown list box
`Entry`	Enter a line of text
`Button`	A button
`Radiobutton`	A toggle set, with only one active item
`Scale`	A slider
`Spinbox`	An integer spinner

There are a few more widgets in Tkinter, but they don't fit so well for a quick demo example! You can see them all by checking the TkDocs.

Now, we'll step through each of those widgets in turn, adding them to our application and seeing how they behave.

`Label`

We'll start the tour with Label, arguably one of the simplest widgets available in the Tkinter toolbox. This is a simple one-line piece of text that you can position in your application. You can set the text by passing in a str as you create it:

python

label = tk.Label(self, text="Hello")

Or, by using the .config() function:

python

label = tk.Label(self, text="1")  # The label is created with the text 1.
label.config(text="2")   # The label now shows 2.

You can also adjust font properties, such as the family and size. Here's an app that showcases these features:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Label")
root.geometry("200x80")

label = tk.Label(root, text="Hello!", font=("Helvetica", 30))
label.pack(expand=True)

root.mainloop()

Tkinter's Label Widget on macOS

Note that if you want to change the properties of a widget font, it is usually better to set the font when creating the widget to ensure consistency.

The alignment is specified by using the anchor configuration option. The possible horizontal text alignments are:

Option	Behavior
`"w"`, `tk.W` (for West)	Aligns with the left edge
`"e"`, `tk.E` (for East)	Aligns with the right edge
`"center"`, `tk.CENTER`	Centers horizontally in the available space

The options available for vertical alignment are:

Option	Behavior
`"n"`, `tk.N` (for North)	Aligns with the top
`"s"`, `tk.S` (for South)	Aligns with the bottom
`"center"`, `tk.CENTER`	Centers vertically in the available space

You can combine these by setting the anchor option:

python

label = tk.Label(self, text="Hello", anchor="center")

Note that you use the anchor option to combine the alignment settings.

Finally, you can also use Label to display an image using PhotoImage. This function accepts an image file, and you can create it as follows:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Label Image")

photo = tk.PhotoImage(file="otje.png").subsample(2)
label = tk.Label(root, image=photo)
label.pack(expand=True)

root.mainloop()

Otje, the cat, displayed in a window

What a lovely face!

`Button`

The Button widget is one of the most commonly used widgets in Tkinter. It represents a clickable button that can trigger an action when pressed. We typically use buttons for submitting forms, opening dialogs, or starting processes.

Here's a simple example:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Button")
root.geometry("200x100")

def on_click():
    label.config(text="Button clicked!")

button = tk.Button(
    root,
    text="Click Me",
    command=on_click,
)
button.pack(padx=5, pady=5)

# A helper label to show the result of the click
label = tk.Label(root, text="Waiting for click...")
label.pack(padx=5, pady=5)

root.mainloop()

Tkinter's Button Widget on macOS

In this example, you create a button with the label "Click Me". The command argument connects the button to the on_click() function, which updates the label's text when we click the button.

You can customize the button by adjusting its width, height, font, bg (background color), and fg (foreground/text color). For example:

python

button = tk.Button(
    root,
    text="Styled Button",
    bg="blue",
    fg="white",
    font=("Arial", 14)
)

Buttons are versatile and form the backbone of interactive Tkinter applications.

`Checkbutton`

The next widget to explore is Checkbutton. As its name suggests, it presents a checkable box to the user. As with all Tkinter widgets, it has a number of configuration options to change the widget behaviors:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Checkbutton")
root.geometry("210x80")

def show_state():
    checked = "Checked" if var.get() else "Unchecked"
    checkbox.config(text=f"Check me! ({checked})")

var = tk.IntVar()
checkbox = tk.Checkbutton(root, text="Check me! (Checked)", variable=var)
checkbox.select()
checkbox.config(command=show_state)
checkbox.pack(padx=5, pady=10)

root.mainloop()

Tkinter's Checkbutton Widget on macOS

You can programmatically set a checkbox state using select() or deselect(). You can access the state using a tk.IntVar() variable, which holds the checkbox's state: 1 for checked and 0 for unchecked.

`Combobox`

The Combobox widget is a drop-down list, closed by default with an arrow to open it. You can select a single item from the list, and the currently selected item is shown as a label on the widget. The combo box is suited to selecting a choice from a long list of options.

You can add items to a Combobox by passing a list of strings to its values argument. The items will be added in the order we provide them:

python

import tkinter as tk
from tkinter import ttk

root = tk.Tk()
root.title("Tkinter Combobox")
root.geometry("200x80")

def selection_changed(event):
    label.config(text=f"{event.widget.get()} selected!")

combobox = ttk.Combobox(root, values=["One", "Two", "Three"])
combobox.set("One")
combobox.bind("<<ComboboxSelected>>", selection_changed)
combobox.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, text="One selected!")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Combobox Widget on macOS

In this example, we create a combo box whose values come from a Python list. Then, we set the current value to "One" with the set() function.

The bind() function connects the <<ComboboxSelected>> event to the selection_changed() function. This event is triggered when the currently selected item changes. The function updates the text of the helper label to reflect the selected item.

Combobox widgets can also be editable, allowing users to enter values not currently in the list. To achieve this, you need to set the state argument to "normal":

python

widget.config(state="normal")

You can also set a limit to the number of items allowed by configuring the list or using custom validation.

`Listbox`

The Listbox widget is similar to Combobox, except that its options are presented as a scrollable list of items. It also supports the selection of multiple items at once. The Listbox class offers a <<ListboxSelect>> event that sends the selected item's index:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Listbox")

def selection_changed(event):
    selection = event.widget.curselection()
    if selection:
        index = selection[0]
        label.config(text=f"{event.widget.get(index)} selected!")
        event.widget.get(index)

listbox = tk.Listbox(root)
for item in ["One", "Two", "Three"]:
    listbox.insert(tk.END, item)
listbox.bind("<<ListboxSelect>>", selection_changed)
listbox.pack(padx=5, pady=5, fill="both", expand=True)

# A helper label to show the selected value
label = tk.Label(root, text="One selected!")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Listbox Widget on macOS

In this example, you create a list box and populate it through a for loop and the insert() function. Then, you connect the "<<ListboxSelect>>" event with the selection_changed() function. The helper label at the bottom of the window shows the selected item.

`Entry`

The Entry widget is a simple single-line text editing box, into which users can type input. These are used for form fields, or settings where there is no restricted list of valid inputs. For example, when entering an email address or computer name:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Entry")

def return_pressed(event):
    label.config(text=event.widget.get())

entry = tk.Entry(root)
entry.insert(0, "Enter your text")
entry.bind("<Return>", return_pressed)
entry.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, text="Entry demo!")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Entry Widget on macOS

In this example, you create a text entry using the Entry widget. Then, you insert a placeholder text using the insert() function. The Entry widget allows you to handle various text events, including when the Return key is pressed. Binding this even to return_pressed() ensures that when you press Enter, the helper label displays the text that you type into the entry.

The Entry class has several useful features. They even allow you to perform input validation using custom validation functions and regular expressions.

`Spinbox`

The Spinbox widget provides an input box for numerical values. It has arrows to increase and decrease the value. It supports integers natively:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Spinbox")
root.geometry("200x80")

spinbox_var = tk.StringVar(value="0")
spinbox = tk.Spinbox(
    root,
    from_=-10,
    to=10,
    textvariable=spinbox_var,
)
spinbox.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, textvariable=spinbox_var)
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Tkinter's Spinbox Widget on macOS

The code above shows the various features available for the Spinbox widget. You can set the interval extremes with the from_ and to arguments. In practice, you'll often use the textvariable option to control the spin box value.

`Scale`

The Scale widget provides a slide-bar widget that works much like a Spinbox. Rather than displaying the current value numerically, it displays the position of the slider handle along the length of the widget.

This widget is often useful when we need to adjust between two extremes but where absolute accuracy is not required. The most common use of this type of widget is for volume controls in multimedia apps:

python

import tkinter as tk

root = tk.Tk()
root.title("Tkinter Scale")
root.geometry("200x80")

def value_changed(event):
    label.config(text=event.widget.get())

scale = tk.Scale(root, from_=0, to=10, orient="horizontal")
scale.bind("<Motion>", value_changed)
scale.pack(padx=5, pady=5, fill="x")

# A helper label to show the selected value
label = tk.Label(root, text="0")
label.pack(padx=5, pady=5, fill="x")

root.mainloop()

Run this and you'll see a slider widget. Drag the slider to change the value.

Tkinter's Scale Widget on macOS

You can also construct a slider with a vertical or horizontal orientation by setting the orient option.

Conclusion

This concludes our brief tour of the common widgets used in Tkinter applications. To see the full list of available widgets, including all their options and attributes, take a look at the Tkinter Documentation or TkDocs site.

What does @Slot() do? — Is the Slot decorator even necessary?

2025-05-12T06:00:00+00:00

When working with Qt slots and signals in PySide6 you will discover the @Slot decorator. This decorator is used to mark a Python function or method as a slot to which a Qt signal can be connected. However, as you can see in our PySide6 signals and slots tutorial you don't have to use this. Any Python function or method can be used, normally, as a slot for Qt signals. But elsewhere, in our PySide6 multithreading tutorial we do use it.

What's going on here?

Why do you sometimes use @Slot but usually not?
What happens when you omit the @Slot decorator?
Are there times when @Slot is required?

If you're looking for the PyQt6 equivalent of this article, see What does @pyqtSlot() do?.

What Does the PySide6 Documentation Say About @Slot?

The PyQt6 documentation has a good explanation:

Although PyQt6 allows any Python callable to be used as a slot when connecting signals, it is sometimes necessary to explicitly mark a Python method as being a Qt slot and to provide a C++ signature for it. PyQt6 provides the pyqtSlot() function decorator to do this.

Connecting a signal to a decorated Python method has the advantage of reducing the amount of memory used and is slightly faster.

In PySide6 the decorator is named simply Slot() but is otherwise functionally compatible:

PySide6 adopts PyQt's new signal and slot syntax as-is. The PySide6 implementation is functionally compatible with the PyQt one [...].

From the above we see that:

Any Python callable can be used as a slot when connecting signals.
It is sometimes necessary to explicitly mark a Python method as being a Qt slot and to provide a C++ signature for it.
There is a side-benefit in that marking a function or method with Slot() reduces the amount of memory used, and makes the slot faster.

When Is the @Slot Decorator Required in PySide6?

Sometimes necessary is a bit vague. In practice the only situation where you need to use @Slot decorators is when working with threads. This is because of a difference in how signal connections are handled in decorated vs. undecorated slots.

If you decorate a method with @Slot then that slot is created as a native Qt slot, and behaves identically to a C++ slot.
If you don't decorate the method then PySide6 will create a "proxy" object wrapper which provides a native slot to Qt.

In normal use this is fine, aside from the performance impact (see below). But when working with threads, there is a complication: is the proxy object created on the GUI thread or on the runner thread? If it ends up on the wrong thread, this can lead to segmentation faults. Using the @Slot decorator side-steps this issue, because no proxy is created.

When updating my PySide6 book I wondered -- is this still necessary?! -- and tested removing it from the examples. Many examples continue to work, but some failed. To be safe, always use @Slot decorators on your QRunnable.run methods.

For more on working with threads safely in PySide6, see our complete guide to multithreading PySide6 applications with QThreadPool.

@Slot Performance Benchmark: Does It Make a Difference?

We can test this directly by using this script from Oliver L Schoenborn. Updating for PySide6 (replace PyQt5 with PySide6 and pyqtSlot with Slot and it will work as-is) and running this we get the following results:

See the original results for PyQt5 for comparison.

First the results for the speed of emitting signals when connected to a decorated slot, vs non-decorated.

python

Raw slot mean, stddev:  1.608 0.066
Pyqt slot mean, stddev: 1.587 0.045
Percent gain with Slot: 1 %

The result shows @Slot as 1% faster, but this is negligible (the original data on PyQt5 also showed no difference). So, using @Slot will have no noticeable impact on the speed of signal handling in your applications.

Next are the results for establishing connections. This shows the speed and memory usage of connecting to decorated vs. non-decorated slots.

python

Comparing mem and time required to create 10000000 connections, 1000 times

Measuring for 100000 connections
              # connects   mem (bytes)       time (sec)
Raw         :   100000     38670336 (36MB)    0.381
PySide Slot :   100000     17858560 (17MB)    0.426
Ratios      :                     2               1

The results show that decorated slots are marginally faster to connect to, but the difference is negligible. Based on these numbers, when connecting 100 signals the total execution time difference would be 0.03 ms vs 0.04 ms. This is negligible, not to mention imperceptible.

Perhaps more significant is that using raw connections uses 2x the memory of decorated connections. Again though, bear in mind that for a more realistic upper limit of connections (100) the actual difference here is 3.6KB vs 1.7KB.

The bottom line: don't expect any dramatic improvements in performance or memory usage from using @Slot decorators, unless you're working with insanely large numbers of signals or making regular connections you won't see any difference at all. That said, decorating your slots is an easy win if you need it.

Using @Slot to Overload Signal Types in PySide6

In Qt, signals can be used to transmit more than one type of data by overloading signals and slots with different types. For more on passing data through signals, see our tutorial on transmitting extra data with Qt signals in PySide6.

For example, with the following code the my_slot_fn will only receive signals which match the signature of two int values.

python

@Slot(int, int)
def my_slot_fn(a, b):
    pass

Conclusion: When Should You Use @Slot in PySide6?

The @Slot decorator can be used to mark Python functions or methods as Qt slots in PySide6. This decorator is only required on slots which may be connected to across threads, for example the run method of QRunnable objects. For all other slots it can be omitted. There is a very small performance benefit to using it, which you may want to consider when your application makes a large number of signal-slot connections.

To summarize when you need the @Slot decorator:

Threading with QRunnable or QThread: Always use @Slot on methods that will be called across threads to avoid segmentation faults. See our PySide6 QThreadPool tutorial for practical examples.
Normal signal-slot connections: The decorator is optional. Any Python callable works as a slot without it. Learn more in our PySide6 signals, slots & events guide.
Performance-critical applications: Use @Slot if you have thousands of connections and need to reduce memory overhead, though the gains are minimal for typical applications.

Not sure whether to use PySide6 or PyQt6 for your project? See our comparison of PyQt6 vs PySide6 to help you decide.

For an in-depth guide to building Python GUIs with PyQt5 see my book, Create GUI Applications with Python & Qt5.

Build an Image Noise Reduction Tool with Streamlit and OpenCV — Clean up noisy images using OpenCV denoising algorithms in Python

2025-05-05T06:00:00+00:00

Image noise is a random variation of brightness or color in images, which can make it harder to discern finer details in a photo. Noise is an artefact of how the image is captured. In digital photography, sensor electronic noise causes random fuzziness over the true image. It is more noticeable in low light, where the lower signal from the sensor is amplified, amplifying the noise with it. Similar noisy artifacts are also present in analog photos and film, but there it is caused by the film grain. Finally, you can also see noise-like artifacts introduced by lossy compression algorithms such as JPEG.

Noise reduction or denoising improves the visual appearance of a photo and can be an important step in a larger image analysis pipeline. Eliminating noise can make it easier to identify features algorithmically. However, we need to ensure that the denoised image is still an accurate representation of the original capture.

Denoising is a complex topic. Fortunately, several different algorithms are available in Python. In this tutorial, we'll use algorithms from OpenCV and build them into a Streamlit web app. The app will allow a user to upload images, choose from common noise reduction algorithms — such as Gaussian Blur, Median Blur, Minimum Blur, Maximum Blur, and Non-local Means — and adjust the strength of the noise reduction using a slider. The user can then download the resulting noise-reduced image.

By the end of this tutorial, you will --

Learn how to build interactive Python web applications with Streamlit.
Understand how to work with images using the Python libraries OpenCV and Pillow.
Be able to apply noise reduction algorithms to images and allow users to download the processed images in different formats.

There's quite a lot to this example, so we'll break it down into small steps to make sure we understand how everything works.

Setting Up the Python Working Environment

In this tutorial, we'll use the Streamlit library to build the noise reduction app's GUI.

To perform the denoising, we'll be using OpenCV. Don't worry if you're not familiar with this library, we'll be including working examples you can copy for everything we do.

With that in mind, let's create a virtual environment and install our requirements into it. To do this, you can run the following commands:

macOS
Windows
Linux

sh
$ mkdir denoise/
$ cd denoise
$ python -m venv venv
$ source venv/bin/activate
(venv)$ pip install streamlit opencv-python pillow numpy

cmd
> mkdir denoise/
> cd denoise
> python -m venv venv
> venv\Scripts\activate.bat
(venv)> pip install streamlit opencv-python pillow numpy

sh
$ mkdir denoise/
$ cd denoise
$ python -m venv venv
$ source venv/bin/activate
(venv)$ pip install streamlit opencv-python pillow numpy

With these commands, you create a denoise/ folder for storing your project. Inside that folder, you create a new virtual environment, activate it, and install Streamlit, OpenCV, Pillow & numpy.

For platform-specific troublshooting, check the Working With Python Virtual Environments tutorial.

Building the Streamlit Application Outline

We'll start by constructing a simple Streamlit application and then expand it from there.

python

import streamlit as st

# Set the title of our app.
st.title("Noise Reduction App")

Save this file as app.py and use the following command to run it:

python

streamlit run app.py

Streamlit will start up and will launch the application in your default web browser.

The Streamlit application title displayed in the browser.

If it doesn't launch by itself, you can see the web address to open in the console.

The Streamlit application launch message showing the local server address where the app can be viewed.

Now that we have the app working, we can step through and build up our app.

Uploading an Image with Streamlit

First we need a way to upload an image to denoise. Streamlit provides a simple .file_uploader method which can be used to upload an image from your computer. This is a generic file upload handler, but you can provide both a message to display (to specify what to upload) and constrain the file types that are supported.

Below we define a file_uploader which shows a message "Choose an image..." and accepts JPEG and PNG images.

python

import streamlit as st

# Set the title of our app.
st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])

print(uploaded_file)

For historic reasons, JPEG images can have both .jpg or .jpeg extensions, so we include both in the list.

Run the code and you'll see the file upload box in the app. Try uploading a file.

Streamlit application with a file-upload widget.

The uploaded image is stored in the variable uploaded_file. Before a file is uploaded, the value of uploaded_file will be None. Once the user uploads an image, this variable will contain an UploadedFile object.

python

None
UploadedFile(file_id='73fd9a97-9939-4c02-b9e8-80bd2749ff76', name='headcake.jpg', type='image/jpeg', size=652805, _file_urls=file_id: "73fd9a97-9939-4c02-b9e8-80bd2749ff76"
upload_url: "/_stcore/upload_file/7c881339-82e4-4d64-ba20-a073a11f7b60/73fd9a97-9939-4c02-b9e8-80bd2749ff76"
delete_url: "/_stcore/upload_file/7c881339-82e4-4d64-ba20-a073a11f7b60/73fd9a97-9939-4c02-b9e8-80bd2749ff76"
)

We can use this UploadedFile object to load and display the image in the browser.

How Streamlit Re-evaluation Works

If you're used to writing Python scripts the behavior of the script and file upload box might be a confusing. Normally a script would execute from top to bottom, but here the value of uploaded_file is changing and the print statement is being re-run as the state changes.

There's a lot of clever stuff going on under the hood here, but in simple terms the Streamlit script is being re-evaluated in response to changes. On each change the script runs again, from top to bottom. But importantly, the state of widgets is not reset on each run.

When we upload a file, that file gets stored in the state of the file upload widget and this triggers the script to re-start. When it gets to the st.file_uploader call, that UploadedFile object will be returned immediately from the stored state. It can then affect the flow of the code after it.

The following code allows you to see these re-runs more clearly, by displaying the current timestamp in the header. Every time the code is re-executed this number will update.

python

from time import time

import streamlit as st

# Set the title of our app.
st.title(f"Noise Reduction App {int(time())}")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])

Try uploading an image and then removing it. You'll see the timestamp in the title change each time. This is the script being re-evaluated in response to changes in the widget state.

Loading and Displaying the Uploaded Image

While we can upload an image, we can't see it yet. Let's implement that now.

As mentioned, the uploaded file is available as an UploadedFile object in the uploaded_file variable. This object can be passed directly to st.image to display the image back in the browser. You can also add a caption and auto resize the image to the width of the application.

python

import numpy as np
import streamlit as st
from PIL import Image

st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])


if uploaded_file is not None:
    # Convert the uploaded file to a PIL image.
    image = Image.open(uploaded_file)

    st.image(image, caption="Uploaded Image", use_container_width=True)

Run this and upload an image. You'll see the image appear under the file upload widget.

Streamlit application showing an uploaded image.

Converting the Image to a NumPy Array for OpenCV Processing

While the above works fine for displaying the image in the browser, we want to process the image through the OpenCV noise reduction algorithms. For that we need to get the image into a format which OpenCV recognizes. We can do that using Pillow & NumPy.

The updated code to handle this conversion is shown below.

python

import numpy as np
import streamlit as st
from PIL import Image

st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])


if uploaded_file is not None:
    # Convert the uploaded file to a PIL image.
    image = Image.open(uploaded_file)

    # Convert the image to an RGB NumPy array for processing.
    image = image.convert("RGB")
    image = np.array(image)

    # Displaying the RGB image.
    st.image(image, caption="Uploaded Image", use_container_width=True)

In this code, the uploaded file is opened using Pillow's Image.open() method, which reads the image into a PIL image format. The image is then converted into Pillow's RGB format, for consistency (discarding transparency for example). This regular format is then converted into a NumPy array which OpenCV requires for processing.

Helpfully, Streamlit's st.image method also understands the NumPy RGB image format, so we can pass the image array directly to it. This will be useful when we want to display the processed image, since we won't need to convert it before doing that.

If you run the above it will work exactly as before. But now we have our uploaded image available as an RGB array in the image variable. We'll use that to do our processing next.

Configuring the Noise Reduction Algorithm

The correct noise reduction strategy depends on the image and type of noise present. For a given image you may want to try different algorithms and adjust the extent of the noise reduction. To accommodate that, we're going to add two new controls to our application -- an algorithm drop down, and a kernel size slider.

The first presents a select box from which the user can choose which algorithm to use. The second allows the user to configure the behavior of the given algorithm -- specifically the size of the area being considered by each algorithm when performing noise reduction.

python

import numpy as np
import streamlit as st
from PIL import Image

st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])

algorithm = st.selectbox(
    "Select noise reduction algorithm",
    (
        "Gaussian Blur Filter",
        "Median Blur Filter",
        "Minimum Blur Filter",
        "Maximum Blur Filter",
        "Non-local Means Filter",
    ),
)

kernel_size = st.slider("Select kernel size", 1, 10, step=2)


if uploaded_file is not None:
    # Convert the uploaded file to a PIL image.
    image = Image.open(uploaded_file)

    # Convert the image to an RGB NumPy array for processing.
    image = image.convert("RGB")
    image = np.array(image)

    # Displaying the RGB image.
    st.image(image, caption="Uploaded Image", use_container_width=True)

When you run this you'll see the new widgets in the UI. The uploaded image is displayed last since it is the last thing to be added.

The algorithm selection and configuration widgets shown in the app.

The slider for the kernel size allows the user to adjust the kernel size, which determines the strength of the noise reduction effect. The kernel is a small matrix used in convolution to blur or process the image for noise removal. The larger the kernel size, the stronger the effect will be but also the more blurring or distortion you will see in the image.

The removal of noise is always a balancing act between noise and accuracy of the image.

The slider ranges from 1 to 10, with a step of 2 (i.e., possible kernel sizes are 1, 3, 5, 7, and 9).

The kernel size must be an odd number to maintain symmetry in the image processing algorithms.

Applying Noise Reduction with OpenCV in Python

Now we have all the parts in place to actually perform noise reduction on the image. The final step is to add the calls to OpenCV's noise reduction algorithms and show the resulting, noise-reduced image back in the UI.

python

import cv2
import numpy as np
import streamlit as st
from PIL import Image

st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])

algorithm = st.selectbox(
    "Select noise reduction algorithm",
    (
        "Gaussian Blur Filter",
        "Median Blur Filter",
        "Minimum Blur Filter",
        "Maximum Blur Filter",
        "Non-local Means Filter",
    ),
)

kernel_size = st.slider("Select kernel size", 1, 10, step=2)


if uploaded_file is not None:
    # Convert the uploaded file to a PIL image.
    image = Image.open(uploaded_file)

    # Convert the image to an RGB NumPy array for processing.
    image = image.convert("RGB")
    image = np.array(image)

    # Displaying the RGB image.
    st.image(image, caption="Uploaded Image", use_container_width=True)

    # Applying the selected noise reduction algorithm based on user selection
    if algorithm == "Gaussian Blur Filter":
        denoised_image = cv2.GaussianBlur(image, (kernel_size, kernel_size), 0)
    elif algorithm == "Median Blur Filter":
        denoised_image = cv2.medianBlur(image, kernel_size)
    elif algorithm == "Minimum Blur Filter":
        kernel = np.ones((kernel_size, kernel_size), np.uint8)
        denoised_image = cv2.erode(image, kernel, iterations=1)
    elif algorithm == "Maximum Blur Filter":
        kernel = np.ones((kernel_size, kernel_size), np.uint8)
        denoised_image = cv2.dilate(image, kernel, iterations=1)
    elif algorithm == "Non-local Means Filter":
        denoised_image = cv2.fastNlMeansDenoisingColored(
            image, None, kernel_size, kernel_size, 7, 15
        )

    # Displaying the denoised image in RGB format
    st.image(denoised_image, caption="Denoised Image", use_container_width=True)

If you run this you can now upload your images and apply denoising to them. Try changing the algorithm and adjusting the kernel size parameter to see the effect it has on the noise reduction. The denoised image is displayed at the bottom with the caption "Denoised Image".

Each of the noise reduction strategies is described below. The median blur and non-local means methods are the most effective for normal images.

Gaussian Blur Filter

Gaussian blur smooths the image by applying a Gaussian function to a pixel's neighbors. The kernel size determines the area over which the blur is applied, with larger kernels leading to stronger blurs. This method preserves edges fairly well and is often used in preprocessing for tasks like object detection.

Gaussian blur filter applied to an image using a 3x3 kernel.

This is effective at removing light noise, at the expense of sharpness.

Median Blur Filter

Median blur reduces noise by replacing each pixel's value with the median value from the surrounding pixels, making it effective against salt-and-pepper noise. It preserves edges better than Gaussian blur but can still affect the sharpness of fine details.

Median blur filter applied to an image using a 3x3 kernel window.

Median blur noise reduction (kernel size = 7).

Median blur noise reduction (kernel size = 5).

Minimum Blur Filter (Erosion)

This filter uses the concept of morphological erosion. It shrinks bright areas in the image by sliding a small kernel over it. This filter is effective for removing noise in bright areas but may distort the overall structure if applied too strongly.

Erosion algorithm applied to an image using 3x3 kernel window.

This works well to remove light noise from dark regions.

Erosion noise reduction (kernel size = 5).

Maximum Blur Filter (Dilation)

In contrast to erosion, dilation expands bright areas and is effective in eliminating dark noise spots. However, it can result in the expansion of bright regions, altering the shape of objects in the image.

Dilation algorithm applied to an image using 3x3 kernel window.

This works well to remove dark noise from light regions.

Non-Local Means Denoising Filter

This method identifies similar regions from across the image, then combines these together to average out the noise. This works particularly well in images with repeating regions, or flat areas of color, but less well when the image has too much noise to be able to identify the similar regions.

Non-local means noise reduction example.

Improving the Streamlit Layout with Columns

It's not very user friendly having the input and output images one above the other, as you need to scroll up and down to see the effect of the algorithm. Streamlit has support for arranging widgets in columns. We'll use that to put the two images next to one another.

To create columns in Streamlit you use st.columns() passing in the number of columns to create. This returns column objects (as many as you request) which can be used as context managers to wrap your widget calls. In code, this looks like the following:

python

    # Displaying the denoised image in RGB format
    col1, col2 = st.columns(2)

    with col1:
        st.image(image, caption="Uploaded Image", use_container_width=True)

    with col2:
        st.image(denoised_image, caption="Denoised Image", use_container_width=True)

Here we call st.columns(2) creating two columns, returning into col1 and col2. We then use these with with to wrap the two st.image calls. This puts them into two adjacent columns.

Run this and you'll see the two images next to one another. This makes it much easier to see the impact of changes in the algorithm or parameters.

The source and processed image arranged next to one another using columns.

Downloading the Denoised Image

Our application now allows users to upload images and process them to remove noise, with a configurable noise removal algorithm and kernel size. The final step is to allow users to download and save the processed image somewhere.

You can actually just right-click and use your browser's option to Save the image if you like. But adding this to the UI makes it more explicit and allows us to offer different image output formats.

First, we need to import the io module. In a normal image processing script, you could simply save the generated image to disk. Our Streamlit app could be running on a server somewhere, and saving the result to the server isn't useful: we want to be able to send it to the user. For that, we need to send it to the web browser. Browsers don't understand Python objects, so we need to save our image data to a simple bytes object. The io module allows us to do that.

Add an import for Python's io module to the imports at the top of the code.

python

import io

import cv2
import numpy as np
import streamlit as st
from PIL import Image

Now under the rest of the code we can add the widgets and logic for saving and presenting the image as a download. First add a select box to choose the image format.

python

    # ..snipped the rest of the code.

    # Dropdown to select the file format for downloading
    file_format = st.selectbox("Select output format", ("PNG", "JPEG"))

Next we need to take our denoised_image and convert this from a NumPy array back to a PIL image. Then we can use Pillow's native methods for saving the image to a simple bytestream, which can be sent to the web browser.

python

    # Converting NumPy array to PIL image in RGB mode
    denoised_image_pil = Image.fromarray(denoised_image)

    # Creating a buffer to store the image data in the selected format
    buf = io.BytesIO()
    denoised_image_pil.save(buf, format=file_format)
    byte_data = buf.getvalue()

Since OpenCV operations return a NumPy array (the same format we provide it with) it must be converted back to a PIL image before saving. The io.BytesIO() creates an in-memory file buffer to write to. That way we don't need to actually save the image. We write the image using the Image .save() method in the requested file format.

Note that this saved image is in an actual PNG/JPEG image format at this point, not just pure image data.

We can retrieve the bytes data from the buffer using .getvalue(). The resulting byte_data is a raw bytes object that can be passed to the web browser. This is handled by a Streamlit download button.

python

    # Button to download the processed image
    st.download_button(
        label="Download Image",
        data=byte_data,
        file_name=f"denoised_image.{file_format.lower()}",
        mime=f"image/{file_format.lower()}"
    )

Notice we've also set the filename and mimetype, using the selected file_format variable.

If you're adding additional file formats, be aware that the mimetypes are not always 1:1 with the file extensions. In this case we've used .jpeg since the mimetype is image/jpeg.

Refactoring the Code for Better Structure

The complete code so far is shown below.

python

import io

import cv2
import numpy as np
import streamlit as st
from PIL import Image

st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])

algorithm = st.selectbox(
    "Select noise reduction algorithm",
    (
        "Gaussian Blur Filter",
        "Median Blur Filter",
        "Minimum Blur Filter",
        "Maximum Blur Filter",
        "Non-local Means Filter",
    ),
)

kernel_size = st.slider("Select kernel size", 1, 10, step=2)


if uploaded_file is not None:
    # Convert the uploaded file to a PIL image.
    image = Image.open(uploaded_file)

    # Convert the image to an RGB NumPy array for processing.
    image = image.convert("RGB")
    image = np.array(image)

    # Applying the selected noise reduction algorithm based on user selection
    if algorithm == "Gaussian Blur Filter":
        denoised_image = cv2.GaussianBlur(image, (kernel_size, kernel_size), 0)
    elif algorithm == "Median Blur Filter":
        denoised_image = cv2.medianBlur(image, kernel_size)
    elif algorithm == "Minimum Blur Filter":
        kernel = np.ones((kernel_size, kernel_size), np.uint8)
        denoised_image = cv2.erode(image, kernel, iterations=1)
    elif algorithm == "Maximum Blur Filter":
        kernel = np.ones((kernel_size, kernel_size), np.uint8)
        denoised_image = cv2.dilate(image, kernel, iterations=1)
    elif algorithm == "Non-local Means Filter":
        denoised_image = cv2.fastNlMeansDenoisingColored(
            image, None, kernel_size, kernel_size, 7, 15
        )

    # Displaying the denoised image in RGB format
    col1, col2 = st.columns(2)

    with col1:
        st.image(image, caption="Uploaded Image", use_container_width=True)

    with col2:
        st.image(denoised_image, caption="Denoised Image", use_container_width=True)

    # Dropdown to select the file format for downloading
    file_format = st.selectbox("Select output format", ("PNG", "JPEG", "JPG"))

    # Converting NumPy array to PIL image in RGB mode
    denoised_image_pil = Image.fromarray(denoised_image)

    # Creating a buffer to store the image data in the selected format
    buf = io.BytesIO()
    denoised_image_pil.save(buf, format=file_format)
    byte_data = buf.getvalue()

    # Button to download the processed image
    st.download_button(
        label="Download Image",
        data=byte_data,
        file_name=f"denoised_image.{file_format.lower()}",
        mime=f"image/{file_format.lower()}",
    )

If you run the completed app you can now upload images, denoise them using the different algorithms and kernel parameters and then save them as JPEG or PNG format images.

However, we can still improve this. There is a lot of code nested under the if uploaded_file is not None: branch, and the logic and processing steps aren't well organized -- everything runs together, mixed in with the UI. When developing UI applications it's a good habit to separate UI and non-UI code where possible (logic vs. presentation). That keeps related code together in the same context, aiding readability and maintainability.

Below is the same code refactored to move the file opening, denoising and file exporting logic out into separate handler functions.

python

import io

import cv2
import numpy as np
import streamlit as st
from PIL import Image


def image_to_array(file_to_open):
    """Load a Streamlit image into an array."""
    # Convert the uploaded file to a PIL image.
    image = Image.open(file_to_open)

    # Convert the image to an RGB NumPy array for processing.
    image = image.convert("RGB")
    image = np.array(image)
    return image


def denoise_image(image, algorithm, kernel_size):
    """Apply a denoising algorithm to the provided image, with the given kernel size."""
    # Applying the selected noise reduction algorithm based on user selection
    if algorithm == "Gaussian Blur Filter":
        denoised_image = cv2.GaussianBlur(image, (kernel_size, kernel_size), 0)
    elif algorithm == "Median Blur Filter":
        denoised_image = cv2.medianBlur(image, kernel_size)
    elif algorithm == "Minimum Blur Filter":
        kernel = np.ones((kernel_size, kernel_size), np.uint8)
        denoised_image = cv2.erode(image, kernel, iterations=1)
    elif algorithm == "Maximum Blur Filter":
        kernel = np.ones((kernel_size, kernel_size), np.uint8)
        denoised_image = cv2.dilate(image, kernel, iterations=1)
    elif algorithm == "Non-local Means Filter":
        denoised_image = cv2.fastNlMeansDenoisingColored(
            image, None, kernel_size, kernel_size, 7, 15
        )
    return denoised_image


def image_array_to_bytes(image_to_convert):
    """Given an image array, convert it to a bytes object."""

    # Converting NumPy array to PIL image in RGB mode
    image_pil = Image.fromarray(image_to_convert)

    # Creating a buffer to store the image data in the selected format
    buf = io.BytesIO()
    image_pil.save(buf, format=file_format)
    byte_data = buf.getvalue()
    return byte_data


st.title("Noise Reduction App")

uploaded_file = st.file_uploader("Choose an image...", type=["jpg", "jpeg", "png"])

algorithm = st.selectbox(
    "Select noise reduction algorithm",
    (
        "Gaussian Blur Filter",
        "Median Blur Filter",
        "Minimum Blur Filter",
        "Maximum Blur Filter",
        "Non-local Means Filter",
    ),
)

kernel_size = st.slider("Select kernel size", 1, 10, step=2)


if uploaded_file is not None:
    image = image_to_array(uploaded_file)
    denoised_image = denoise_image(image, algorithm, kernel_size)

    # Displaying the denoised image in RGB format
    col1, col2 = st.columns(2)

    with col1:
        st.image(image, caption="Uploaded Image", use_container_width=True)

    with col2:
        st.image(denoised_image, caption="Denoised Image", use_container_width=True)

    # Dropdown to select the file format for downloading
    file_format = st.selectbox("Select output format", ("PNG", "JPEG", "JPG"))

    byte_data = image_array_to_bytes(denoised_image)

    # Button to download the processed image
    st.download_button(
        label="Download Image",
        data=byte_data,
        file_name=f"denoised_image.{file_format.lower()}",
        mime=f"image/{file_format.lower()}",
    )

As you can see, the main flow of the code now consists entirely of Streamlit UI setup code and calls to the processing functions we have defined. Both the UI and processing code is now easier to read and maintain.

In larger projects you may choose to move the functions out into separate files of related functions and import them into your Streamlit app.

Conclusion

In this tutorial, you built an image noise reduction application using Python, Streamlit, and OpenCV. The app allows users to upload images, apply different noise reduction algorithms — including Gaussian blur, median blur, erosion, dilation, and non-local means denoising — and download the processed image.

It also allows the user to customize the kernel size, which controls the strength of the denoising effect. This makes the app useful for a variety of noise types and image processing tasks.

Streamlit makes it simple to build powerful Python web applications, taking the power of Python's rich ecosystem and making it available through the browser. You can extend this project further by adding more OpenCV filters, supporting additional image formats, or deploying the app to the cloud for others to use.

Kivy's Complex Widgets — Learn How to Use Kivy's Complex UX Widgets in Your Apps

2025-04-28T06:00:00+00:00

Kivy is a powerful framework for developing multi-touch GUI applications using Python. It provides a set of rich built-in widgets which you can use to build complex GUI applications.

In a previous tutorial we covered the basic Kivy widgets such as text inputs, buttons and checkboxes. In this tutorial, we will take things further, exploring some of the more complex widgets that Kivy provides. These include: Bubble, DropDown, FileChooser, Popup, Spinner, RecycleView, TabbedPanel, VideoPlayer, and VKeyboard. With these complex Kivy widgets, you can add advanced features to your Python GUI apps.

Writing an Outline Kivy App

We'll start this tutorial with a simple application skeleton, which we will then modify below. Save the following code in a file named app.py:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout

class WidgetNameApp(App):
    title = "WidgetName Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = BoxLayout()

        return root

WidgetNameApp().run()

Here, we've created a Kivy application with an empty window. The BoxLayout acts as the root widget, this will act as the container to add our complex widgets to. The build() method sets the window's background color to a dark teal shade and adjusts the window size to 360x640 pixels, which is a mobile-friendly size.

To learn more about creating your first Kivy app, check out the Getting Started With Kivy for GUI Development tutorial.

Providing Option Selections With the Kivy `Spinner` Widget

The Kivy Spinner widget is a dropdown selector that allows users to choose one option from multiple choices. This is ideal when working with a list of simple text choices. Below is an example that builds a Spinner that lets you select from different parts of this website.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.spinner import Spinner

class SpinnerApp(App):
    title = "Spinner Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (300, 300)

        root = FloatLayout()

        # Create the Spinner
        spinner = Spinner(
            text="Home",
            values=("Home", "Latest", "FAQ", "Forum", "Contact", "About"),
            size_hint=(None, None),
            size=(200, 70),
            pos_hint={"center_x": 0.2, "center_y": 0.9},
            sync_height=True,
        )

        root.add_widget(spinner)

        return root

SpinnerApp().run()

The Spinner widget works as a simple dropdown list, allowing users to select one option from multiple text choices. We've set the Spinner to start with "Home" as the default text and provided other options ("Latest", "FAQ", "Forum", "Contact", and "About") as a list of values.

You need to repeat the "Home" option in values so that you don't lose it when you select another option.

Run it! You'll get an app that looks as shown below.

A Kivy app showing a Spinner Widget

The dropdown spinner allows users to select from predefined choices. You can use this widget to create elements that work like a dropdown list, optimizing space and providing a clean UI.

Providing Options With the Kivy `DropDown` List Widget

The Kivy DropDown widget provides a more complex menu component that allows users to choose from multiple options. Like the Spinner, this provides an intuitive way for users to select from a set of choices, but here you can display more than just text. This makes it more complex to use, but allows for more flexibility.

Below is an example of using the DropDown widget to create a dropdown list that lets you select your favorite Python GUI library, displayed on a series of Button objects.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.dropdown import DropDown

class DropDownApp(App):
    title = "DropDown Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (200, 200)

        root = BoxLayout(orientation="vertical", padding=10, spacing=10)

        # Create a dropdown with 4 buttons
        dropdown = DropDown()
        for item in ["Kivy", "PyQt6", "PySide6", "Tkinter"]:
            option_btn = Button(text=item, size_hint_y=None, height=50, width=150)
            option_btn.bind(on_release=lambda btn: dropdown.select(btn.text))
            dropdown.add_widget(option_btn)

        # Create a main button to show the dropdown
        button = Button(
            text="Library",
            size_hint=(None, None),
            size=(150, 50),
        )
        button.bind(on_release=dropdown.open)
        dropdown.bind(
            on_select=lambda instance, text: setattr(button, "text", text),
        )
        root.add_widget(button)
        return root

DropDownApp().run()

In this example, we have a DropDown widget that lets the user select a library from a list of options. You populate the dropdown with four options "Kivy", "PyQt6", "PySide6", and "Tkinter", which are displayed in Button objects.

We set each button to trigger the dropdown.select() method when clicked, passing the button's text as the selected value.

Then, we anchor the dropdown to a Library button. When we press the Library button, the dropdown menu opens, displaying the options. Once we select an option, the on_select event updates the main button's text to reflect the chosen library.

Run it! You'll get a window with a dropdown list in the lower left corner. Click in the dropdown widget to change the current selection.

A Kivy app showing a DropDown widget

Accessing Files With the Kivy `FileChooser` Widget

The Kivy filechooser module provides classes for describing, displaying and browsing file systems. In this module there are two ready-made widget views which present the file system as either a list, or as icons. The example below demonstrates both FileChooserIconView and FileChooserListView in action.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.filechooser import FileChooserIconView, FileChooserListView

class FileChooserApp(App):
    title = "FileChooser Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = BoxLayout(orientation="vertical")

        # Create icon-view and list-view file choosers
        filechooser_icons = FileChooserIconView()
        filechooser_list = FileChooserListView()

        root.add_widget(filechooser_icons)
        root.add_widget(filechooser_list)

        return root

FileChooserApp().run()

In this example, we create file chooser widgets to browse and select files using two different views:

Icon view (FileChooserIconView)
List view (FileChooserListView)

The icon view displays files as wrapped rows of icons, clicking on a folder icon will navigate down into that folder. The list view presents them in a list-tree like format, where clicking on a folder will show files and folders nested under it.

Run it! On macOS, you'll see a window that looks something like the following. Try clicking on the folder icons and entries in the list view to see how navigation works in the two examples.

A Kivy app showing file chooser widgets

Building Quick Dialogs With the Kivy `Popup` Widget

The Kivy Popup widget allows us to display modal dialogs with custom content, layouts and widgets. Popups can be used to show messages or ask for input. The following example displays a simple popup message with a title, message and OK button.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.label import Label
from kivy.uix.popup import Popup

class PopupApp(App):
    title = "Popup Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (400, 400)

        root = FloatLayout()

        button = Button(
            text="Open Popup",
            on_press=lambda x: self.show_popup(),
            size_hint=(None, None),
            size=(200, 50),
            pos_hint={"center_x": 0.5, "center_y": 0.5},
        )

        root.add_widget(button)

        return root

    def show_popup(self):
        # Create and show the Popup
        popup = Popup(
            title="Info",
            size_hint=(0.6, 0.6),
            size=(300, 300),
            auto_dismiss=False,
        )

        layout = BoxLayout(orientation="vertical", spacing=10, padding=10)

        message = Label(text="Hello, World!")

        ok_button = Button(text="OK", size_hint=(None, None), size=(80, 40))
        ok_button.bind(on_release=popup.dismiss)

        layout.add_widget(message)
        layout.add_widget(ok_button)

        popup.content = layout
        popup.open()

PopupApp().run()

In this example, you create a Popup widget that displays information as a modal dialog. When the user clicks the Open Popup button, the show_popup() method is triggered, creating a Popup that occupies 60% of the screen in both directions.

We set auto_dismiss to False, which means the popup won't close if we click outside of it. The popup contains the Hello, World! message and an OK button. When we click the button, we dismiss (close) the popup. Popups are effective for displaying alerts, confirmations, or other information in a Kivy app.

Run it! You'll get a window with a button labeled "Open Popup". Click on the Open Popup button to display the popup window.

A Kivy app showing a popup dialog

Creating Contextual Popups With the Kivy `Bubble` Widget

The Kivy Bubble widget is a UI element commonly used for contextual popups, tooltips, or chat applications. Below is a quick Kivy application that shows some text and lets you click on it to change its format. We'll start by importing the necessary objects and subclassing the Bubble class:

python

from kivy.app import App
from kivy.core.window import Window
from kivy.metrics import dp
from kivy.uix.bubble import Bubble, BubbleButton, BubbleContent
from kivy.uix.floatlayout import FloatLayout
from kivy.uix.label import Label

class FormattingBubble(Bubble):
    def __init__(self, target_text, **kwargs):
        super().__init__(**kwargs)

        # Customizing the bubble
        self.size_hint = (None, None)
        self.size = (dp(120), dp(50))
        self.arrow_pos = "top_mid"
        self.orientation = "horizontal"
        self.target_label = target_text

        # Add formatting buttons
        bold_btn = BubbleButton(text="Bold")
        italic_btn = BubbleButton(text="Italic")
        bold_btn.bind(on_release=lambda x: self.on_format("bold"))
        italic_btn.bind(on_release=lambda x: self.on_format("italic"))

        # Add the buttons to the bubble
        bubble_content = BubbleContent()
        bubble_content.add_widget(bold_btn)
        bubble_content.add_widget(italic_btn)

        self.add_widget(bubble_content)

    def on_format(self, format_type):
        if format_type == "bold":
            self.target_label.text = f"[b]{self.target_label.text}[/b]"
        elif format_type == "italic":
            self.target_label.text = f"[i]{self.target_label.text}[/i]"
        self.parent.remove_widget(self)

class BubbleApp(App):
    title = "Bubble Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = FloatLayout()

        self.text = Label(
            text="Click this text to apply formatting",
            size_hint=(0.8, 0.2),
            pos_hint={"center_x": 0.5, "center_y": 0.5},
            markup=True,
        )
        self.text.bind(on_touch_down=self.show_bubble)

        root.add_widget(self.text)
        root.bind(on_touch_down=self.dismiss_bubbles)

        return root

    def show_bubble(self, instance, touch):
        if instance.collide_point(*touch.pos):
            self.remove_all_bubbles()
            bubble = FormattingBubble(target_text=self.text)
            bubble.pos = (
                touch.x - bubble.width / 2, touch.y - bubble.height - dp(10)
            )
            self.root.add_widget(bubble)

    def dismiss_bubbles(self, instance, touch):
        if instance == self.root and not self.text.collide_point(*touch.pos):
            self.remove_all_bubbles()

    def remove_all_bubbles(self):
        for widget in self.root.children[:]:
            if isinstance(widget, FormattingBubble):
                self.root.remove_widget(widget)
                return

BubbleApp().run()

The FormattingBubble class inherits from Bubble and provides text formatting options for a label. It initializes with a specific size, arrow position, and horizontal layout. The bubble will contain two buttons: Bold and Italic. When pressed, these buttons apply the respective formatting to the target text by triggering the on_format() method. This method wraps the text in Kivy's markup tags [b]...[/b] for bold and [i]...[/i] for italic.

The BubbleApp class represents the Kivy application. It sets up a FloatLayout with a centered Label displaying a message. When the user taps the label, the show_bubble() method creates and positions a FormattingBubble above the tapped location.

The app also ensures that only one bubble is visible at a time by removing existing ones before showing a new one. Additionally, tapping outside the label dismisses any active bubbles using the dismiss_bubbles() method.

Run it! The app features a dark teal background and a mobile-friendly window size. The Bubble widget appears when we click the text.

A Kivy app showing a Bubble widget

Displaying Large Data Sets With the Kivy `RecycleView` Widget

The Kivy RecycleView widget efficiently displays large data sets by recycling views or graphical elements. Instead of creating a widget for every item in the dataset, RecycleView reuses a small number of widgets to display visible items only, significantly improving performance.

To illustrate, let's create a view that lets you inspect a database of employee profiles. The data is stored in a CSV file that looks like the following:

csv

name,job,department
John Smith,Developer,IT
Jane Doe,Designer,Graphics
Anne Frank,Artist,Painting
David Lee,Engineer,Civil
Ella Brown,Doctor,Medical
Frank Thomas,Chef,Culinary
Henry Ford,Driver,Transport
Nathan Young,Consultant,Business
Olivia King,Manager,Administration
Peter Wright,Director,Management
Queen Bell,President,Executive
Walter Thompson,Assistant,Support
Xena Garcia,Associate,Associate
Zack Harris,Consultant,Consulting

You can read and load this data with the csv module. To visualize the data, you can create a view with the RecycleView widget. For the individual views, you can use the Button widget, which will let you display the employee's profile:

python

import csv

from kivy.app import App
from kivy.core.window import Window
from kivy.metrics import dp
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.button import Button
from kivy.uix.label import Label
from kivy.uix.popup import Popup
from kivy.uix.recycleboxlayout import RecycleBoxLayout
from kivy.uix.recycleview import RecycleView

class EmployeesView(RecycleView):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.employees_data = self._read_from_csv()

        # Load the employees data into the data attribute
        self.data = [
            {
                "text": f"{employee['name']}",
                "on_release": self._create_callback(employee["name"]),
            }
            for employee in self.employees_data
        ]

        layout_manager = RecycleBoxLayout(
            default_size=(None, dp(56)),
            default_size_hint=(1, None),
            size_hint_y=None,
            orientation="vertical",
        )
        layout_manager.bind(minimum_height=layout_manager.setter("height"))

        self.add_widget(layout_manager)
        self.viewclass = "Button"

    def _create_callback(self, name):
        return lambda: self.on_button_click(name)

    def _read_from_csv(self):
        with open("employees.csv", mode="r") as file:
            return [row for row in csv.DictReader(file)]

    def on_button_click(self, name):
        popup = Popup(
            title=f"{name}'s Profile",
            size_hint=(0.8, 0.5),
            size=(300, 300),
            auto_dismiss=False,
        )
        employees_data = [
            employee for employee in self.employees_data if employee["name"] == name
        ]
        profile = "\n".join(
            [f"{key.capitalize()}: {value}" for key, value in employees_data[0].items()]
        )
        layout = BoxLayout(orientation="vertical", spacing=10, padding=10)
        message = Label(text=profile)
        ok_button = Button(text="OK", size_hint=(None, None))
        ok_button.bind(on_release=popup.dismiss)
        layout.add_widget(message)
        layout.add_widget(ok_button)
        popup.content = layout
        popup.open()

class RecycleViewApp(App):
    title = "RecycleView Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        return EmployeesView()

RecycleViewApp().run()

In this example, we subclass RecycleView to display the list of employees loaded from a CSV file. The _read_from_csv() method opens the file and reads the data using the csv.DictReader() class, which converts each CSV line into a dictionary whose keys come from the file header line.

The data attribute is key for the app to work because it'll hold the data that we want to display. To arrange widgets in a RecycleView, we use a RecycleBoxLayout. The viewclass attribute lets us set the widget that we'll use to display each data item.

It's important to note that for the RecycleView to work properly, we should set viewclass at the end when the data is already loaded and the layout is set up.

Then, we populate the RecycleView view with buttons, each displaying an employee's name. Clicking a button triggers _create_callback(), which generates a callback that opens a popup displaying the selected employee's profile details.

Run it! You'll get a nice-looking window listing the employees. Click a button to view the associated employee's profile. Scroll down to load more profiles.

A Kivy app showing a RecycleView Widget

Building Tabbed UIs With the Kivy `TabbedPanel` Widget

The Kivy TabbedPanel widget lets us organize content into tabs, to improve navigation and optimize the use of space. This is commonly used in settings dialogs where there are lots of options available.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.label import Label
from kivy.uix.tabbedpanel import TabbedPanel, TabbedPanelHeader

class TabbedPanelApp(App):
    title = "TabbedPanel Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        # Create the TabbedPanel
        root = TabbedPanel(do_default_tab=False)

        # Create the tabs
        general_tab = TabbedPanelHeader(text="General")
        general_content = BoxLayout(orientation="vertical", padding=10, spacing=10)
        general_content.add_widget(Label(text="General Settings", font_size=40))
        general_tab.content = general_content
        root.add_widget(general_tab)

        editor_tab = TabbedPanelHeader(text="Editor")
        editor_content = BoxLayout(orientation="vertical", padding=10, spacing=10)
        editor_content.add_widget(Label(text="Editor Settings", font_size=40))
        editor_tab.content = editor_content
        root.add_widget(editor_tab)

        profile_tab = TabbedPanelHeader(text="Profile")
        profile_content = BoxLayout(orientation="vertical", padding=10, spacing=10)
        profile_content.add_widget(Label(text="User Profile", font_size=40))
        profile_tab.content = profile_content
        root.add_widget(profile_tab)

        return root

TabbedPanelApp().run()

In this example, we create a Kivy app that shows a tabbed interface using the TabbedPanel widget. It disables the default tab and manually adds three tabs: General, Editor, and Profile, each represented by a TabbedPanelHeader object.

Inside the tabs, we place a BoxLayout to hold a label that displays a description as a placeholder tab content. Tabs allow us to organize content into visually distinct sections within an application's UI.

Run it! Your app will display three tabs. When you click the tab header, the app shows the tab's content. The active tab shows a light blue line at the bottom.

A Kivy app showing a TabbedPanel Widget

Try and add some more widgets to each tab panel.

Allowing User Input With the Kivy `VKeyboard` Widget

The Kivy VKeyboard widget allows you to create a virtual keyboard that is useful for touchscreen applications that require the user to type in text. Below is a short app that demonstrates a virtual keyboard in action. When you type text using the keyboard, it is displayed on the label.

python

from kivy.app import App
from kivy.core.window import Window
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.label import Label
from kivy.uix.vkeyboard import VKeyboard

class VKeyboardApp(App):
    title = "VKeyboard Widget"

    def build(self):
        Window.clearcolor = (0, 0.31, 0.31, 1.0)
        Window.size = (360, 640)

        root = BoxLayout(orientation="vertical")

        self.display_label = Label(text="Type in!", font_size=40)
        root.add_widget(self.display_label)

        # Create the virtual keyboard
        keyboard = VKeyboard(size_hint=(1, 0.4))
        keyboard.bind(on_key_up=self.keyboard_on_key_up)
        root.add_widget(keyboard)

        return root

    def keyboard_on_key_up(self, *args):
        keycode = args[1]
        text = args[2]
        if keycode == "backspace":
            if (
                len(self.display_label.text) > 0
                and self.display_label.text != "Type in!"
            ):
                self.display_label.text = self.display_label.text[:-1]
                if self.display_label.text == "":
                    self.display_label.text = "Type in!"
        elif keycode == "spacebar":
            if self.display_label.text == "Type in!":
                self.display_label.text = " "
            else:
                self.display_label.text += " "
        elif keycode in {"enter", "shift", "alt", "ctrl", "escape", "tab", "capslock"}:
            pass
        else:
            if self.display_label.text == "Type in!":
                self.display_label.text = text
            else:
                self.display_label.text += text

VKeyboardApp().run()

In this example, we manually add a virtual keyboard to our app's interface using the VKeyboard widget and display typed text using a label.

When a key is released, the keyboard_on_key_up() method processes the input. Printable characters are appended to the label text. Backspace removes the last character, and the spacebar inserts a space.

You typically wouldn't use the VKeyboard widget as in the example above. Input widgets, like TextInput, will automatically bring up the virtual keyboard when focused on mobile devices.

We ignore special keys like Enter, Shift, Alt, Ctrl, and Escape. This allows us to interact with a virtual keyboard and see the input displayed dynamically in the label.

Run it! A virtual keyboard appears at the button of the app's window, allowing you to enter text in touch-based devices. When you type on the virtual keyboard at the bottom of the app's window, the label reflects what you've typed.

A Kivy app showing a VKeyboard Widget

Conclusion

Kivy provides a rich set of complex UX widgets that you can use to create cross-platform Python GUI applications. In this tutorial, you learned how to use the Spinner for dropdown selections, DropDown for custom menus, FileChooser for file browsing, Popup for modal dialogs, Bubble for contextual popups, RecycleView for efficiently displaying large data sets, TabbedPanel for tabbed interfaces, and VKeyboard for virtual keyboard input. Using the examples above as inspiration, you should now be able to integrate these complex Kivy widgets into your own Python apps. See if you can extend these examples further, adding more widgets or functionality to them.

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Python GUIs

Handling Image Drag and Drop from Web Browsers in PyQt6 — Why toLocalFile() returns an empty string and how to handle remote image drops correctly

How drag and drop MIME data works

Why toLocalFile() returns an empty string

Inspecting what the browser actually sends

Handling all cases in your drop event

Checking for local files first

Handling remote URLs

Handling raw image data

Extracting URLs from HTML

Complete working example

What's happening in the complete example

Constantly Print Subprocess Output While Process is Running — How to stream live output from a subprocess into your PyQt6 GUI without freezing the interface

The wrong approach

Streaming Subprocess Output with QProcess

How QProcess Streams Output in Real Time

Running Complex Bash Commands with QProcess

Streaming Subprocess Output Using QThread and subprocess.Popen

How QThread with subprocess.Popen Works

Fixing Delayed Subprocess Output: Buffering Issues

QProcess vs QThread: Which Approach Should You Use?

Complete Example: Live Build Output Viewer in PyQt6

Why Widgets Appear as Separate Windows — Understanding widget parenting in Qt and how to fix widgets that float outside your main window

How Qt decides what's a window

Three ways to Get a Parent-less Widget

Creating widgets without a parent

Accidentally recreating a widget

Losing the parent reference

A clean approach to dynamic tabs

Summary

How to Set Row Background Colors in a QTableView — Use Qt's BackgroundRole to color entire rows based on your data

Understanding How data() Works

A Complete Working Example

How Colors are Set on Rows

Making the Text Readable

Updating Colors Dynamically

Summary

Authentication and Authorization with PyQt6 or PySide6 — Secure your desktop applications with login flows, token-based auth, and role-based access control

Approaches to Authentication in Desktop Apps

Setting Up a Simple Auth Server (For Testing)

Building the Login Dialog

Creating an Auth Manager

Wiring Up the Login Flow

Building the Main Window with Role-Based Access

Making Authenticated API Requests

Handling Token Expiration

Security Considerations

Fixing Missing Icons in PyInstaller-Packaged PyQt6 Applications on Windows — Why your app icon disappears after packaging and how to fix it

Setting the executable icon with PyInstaller

Windows icon caching

Missing icon file at runtime

Handling --onefile builds

Taskbar grouping with an Application User Model ID

Complete working example

Adding QComboBox to a QTableView and getting/setting values after creation — Use QItemDelegate to embed combo boxes in your table views, with per-row data and value tracking

How delegates work in Qt's Model/View framework

Setting up the model and view

Creating the combo box delegate

Running the application

Getting the selected value

Setting a value programmatically

Why each row gets its own combo box items

Complete code

Wrapping up

How to Add Custom Widgets to Qt Designer — Use widget promotion to integrate your own Python widgets into Qt Designer layouts

What is Widget Promotion?

Creating a Custom Widget

Setting Up Your Project Structure

Promoting a Widget in Qt Designer

Place a base widget on your form

Open the Promote Widgets dialog

Fill in the promotion details

Add and promote

Promoting additional widgets

Loading the UI in Python

Using Compiled UI Files

A More Practical Example: Embedding PyQtGraph

Promoting Widgets from Submodules

Troubleshooting Common Issues

Summary

Streaming Subprocess Output with `QProcess`

How `QProcess` Streams Output in Real Time

Running Complex Bash Commands with `QProcess`

Streaming Subprocess Output Using `QThread` and `subprocess.Popen`

How `QThread` with `subprocess.Popen` Works

`QProcess` vs `QThread`: Which Approach Should You Use?

Understanding How `data()` Works

Handling `--onefile` builds

Returning the check state in `data()`

Handling user clicks in `setData()`

Enabling user interaction with `flags()`