How can I import a pyqtgraph HistogramLUTWidget with a .ui file

I can promote a QWidget to pyqtgraph's PlotWidget in Qt Designer without any issues, but when I try to do the same for HistogramLUTWidget, I just get an empty plot. What are the correct promotion settings to embed a HistogramLUTWidget in a .ui file?

If you've been using pyqtgraph's PlotWidget inside Qt Designer (by promoting a QWidget), you might expect the exact same approach to work for HistogramLUTWidget. It does — but the promotion details are slightly different, and getting them wrong gives you an empty plot instead of a working histogram. This tutorial walks through the correct way to embed a HistogramLUTWidget in your .ui file and connect it to an image in your code.

Widget Promotion in Qt Designer

Qt Designer doesn't know about pyqtgraph widgets natively. To use them, you place a regular QWidget in your layout and then promote it to the pyqtgraph class you want. When you load the .ui file at runtime, Qt replaces that placeholder QWidget with the actual pyqtgraph widget.

If you've already done this for PlotWidget, you'll be familiar with the process. For PlotWidget, the promoted class header is pyqtgraph, and the class name is PlotWidget. The HistogramLUTWidget lives in a different module, so the header path is different — and that's where things go wrong.

If you're new to using Qt Designer with Python, the first steps with Qt Designer tutorial covers the basics of creating .ui files and loading them in your application.

The Common Mistake

A natural first attempt is to promote the QWidget to HistogramLUTItem (the graphics item) or to use pyqtgraph as the header file. The HistogramLUTItem is a graphics scene item — it's designed to live inside a GraphicsView, not to be used as a standalone widget. What you actually want is HistogramLUTWidget, which is a proper QWidget subclass that wraps the item and can be placed directly in a layout.

If you promote to the wrong class or use the wrong header, you'll end up with an empty widget or a plain PlotWidget that doesn't respond to setImageItem().

Setting Up the Promotion in Qt Designer

Open your .ui file in Qt Designer and follow these steps:

1. Add a QWidget to your layout wherever you want the histogram to appear. Give it a meaningful object name, such as histogramWidget.

2. Right-click the QWidget and select Promote to... from the context menu.

3. In the promotion dialog, fill in the following:

4. Promoted class name: HistogramLUTWidget

5. Header file: pyqtgraph.widgets.HistogramLUTWidget

6. Click Add, then select the new entry in the list and click Promote.

7. Save the .ui file.

The header file path pyqtgraph.widgets.HistogramLUTWidget tells the .ui loader where to import the class from. This maps to from pyqtgraph.widgets.HistogramLUTWidget import HistogramLUTWidget at runtime — which is exactly the import path that pyqtgraph expects.

For comparison, here are the promotion settings for the two widgets side by side:

The difference is in the header file. PlotWidget is importable directly from the top-level pyqtgraph module, but HistogramLUTWidget needs the full submodule path.

Using the Widget in Code

Once the .ui file is set up, load it in your Python code with uic.loadUi(). The promoted widget is automatically created as a HistogramLUTWidget instance, accessible through the object name you gave it in Designer.

Here's what that looks like. This assumes your .ui file has a promoted HistogramLUTWidget with the object name histogramWidget and a promoted PlotWidget (or GraphicsLayoutWidget) with the object name graphicsView:

import sys
import numpy as np
import pyqtgraph as pg
from PyQt5 import uic
from PyQt5.QtWidgets import QApplication, QMainWindow


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

        # The promoted widget is already available as self.histogramWidget.
        # Set up a ViewBox and ImageItem for the image display.
        self.view = self.graphicsView.addViewBox()
        self.image_item = pg.ImageItem()
        self.view.addItem(self.image_item)

        # Generate some sample image data.
        data = np.random.normal(size=(256, 256)) * 50 + 128
        data = data.clip(0, 255).astype(np.uint8)
        self.image_item.setImage(data)

        # Connect the histogram widget to the image item.
        self.histogramWidget.setImageItem(self.image_item)


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec_())

After uic.loadUi() runs, self.histogramWidget is a fully functional HistogramLUTWidget. You call .setImageItem() to link it to your image, and everything works — the histogram populates, the gradient bar appears, and the LUT controls are interactive.

Complete Working Example (Without a .ui File)

If you want to test the HistogramLUTWidget before wiring up a .ui file, here's a self-contained example that creates everything in code. This is also useful for verifying that your pyqtgraph installation is working correctly:

import sys
import numpy as np
import pyqtgraph as pg
from PyQt5.QtWidgets import QApplication, QMainWindow, QWidget, QHBoxLayout
from pyqtgraph.widgets.HistogramLUTWidget import HistogramLUTWidget


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("HistogramLUTWidget Example")

        # Create the central widget and layout.
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        layout = QHBoxLayout(central_widget)

        # Create a GraphicsLayoutWidget to hold the image.
        self.graphics_widget = pg.GraphicsLayoutWidget()
        layout.addWidget(self.graphics_widget)

        # Create the HistogramLUTWidget.
        # When using a .ui file, this widget is created automatically
        # by the promotion. Here we create it manually.
        self.histogram_widget = HistogramLUTWidget(fillHistogram=False)
        layout.addWidget(self.histogram_widget)

        # Create an ImageItem and add it to a ViewBox.
        self.view = self.graphics_widget.addViewBox()
        self.image_item = pg.ImageItem()
        self.view.addItem(self.image_item)

        # Generate some sample image data.
        data = np.random.normal(size=(256, 256)) * 50 + 128
        data = data.clip(0, 255).astype(np.uint8)
        self.image_item.setImage(data)

        # Connect the histogram to the image.
        self.histogram_widget.setImageItem(self.image_item)

        self.resize(800, 500)


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec_())

Run this and you'll see an image displayed alongside a histogram with a color gradient bar. Dragging the yellow lines on the histogram adjusts the image's brightness and contrast in real time.

For more on using pyqtgraph in your applications, including embedding custom pyqtgraph widgets, see the embedding pyqtgraph custom widgets tutorial. You can also explore plotting with pyqtgraph for a broader introduction to the library.

Troubleshooting

If things aren't working as expected, here are the most common issues:

Empty plot or no histogram displayed. You probably promoted to HistogramLUTItem instead of HistogramLUTWidget, or used pyqtgraph as the header instead of pyqtgraph.widgets.HistogramLUTWidget. Double-check the promotion settings in Designer.

AttributeError when calling setImageItem(). This usually means the widget wasn't promoted correctly, so it's still a plain QWidget or PlotWidget at runtime. Verify that the promotion is actually applied — the widget's class name in Designer's Object Inspector should show HistogramLUTWidget, not QWidget.

Import errors when loading the .ui file. Make sure pyqtgraph is installed (pip install pyqtgraph) and that the header path is exactly pyqtgraph.widgets.HistogramLUTWidget (case-sensitive, no .h extension).

If you're having trouble with widget promotion in general or want to learn more about building complete dialog UIs with Designer, see the creating dialogs with Qt Designer tutorial.

Summary

Embedding a HistogramLUTWidget in a .ui file follows the same promotion pattern as other pyqtgraph widgets, with one difference that matters: the header path. Use pyqtgraph.widgets.HistogramLUTWidget as the header and HistogramLUTWidget as the class name. Once promoted correctly, the widget loads automatically from your .ui file and can be connected to any ImageItem with a single setImageItem() call.