iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To show labels such as month names instead of numbers in PyQtGraph, keep the plotted x coordinates numeric and choose how the axis should turn those positions into text. Use AxisItem.setTicks() for a fixed list of positions and labels, override tickStrings() for labels generated from tick values, or use DateAxisItem when your x values are Unix timestamps.
Choose the right method for your x values
| What your x values represent | Use | How it works |
|---|---|---|
| A fixed set of numeric positions, such as 0, 1, 2 for categories | AxisItem.setTicks() |
Assigns explicit tick positions and their display strings; see the AxisItem API reference. |
| Values that need a label computed at runtime | Override AxisItem.tickStrings() |
Formats the tick values PyQtGraph supplies; see the AxisItem API reference. |
| Actual dates or times encoded as Unix timestamps | DateAxisItem |
Formats dates and adapts the displayed format to the visible time density; see the DateAxisItem API reference. |
Use fixed strings for a known set of positions
For a small, fixed category axis, get the bottom axis and provide tick levels as a nested list. Each tick is a pair: its numeric coordinate and the text to display there.
import pyqtgraph as pg
plot = pg.PlotWidget()
axis = plot.getAxis('bottom')
axis.setTicks([[(0, 'Jan'), (1, 'Feb'), (2, 'Mar')]])
# The x coordinates must align with the positions above.
plot.plot([0, 1, 2], [12, 18, 15])The official AxisItem documentation describes setTicks() as a way to explicitly determine which ticks to display. Its nested input supports major and minor tick levels, with an optional third level. Add levels only when the axis needs them.
Explicit ticks control both the tick locations and their labels. They do not convert string-valued categories into plotting coordinates: the plot data still needs numeric x values. The positions in the tick pairs must correspond to the x coordinates used by the plotted data.
#1 Best Overall
What changes when you call setTicks()
setTicks() overrides the normal tickSpacing(), tickValues(), and tickStrings() behavior for that axis. If you need ticks to change with the visible range, a hard-coded list may become stale; use value-based formatting or a date axis instead.
Generate labels from tick values
When labels follow a rule rather than a short fixed list, subclass AxisItem and override tickStrings(values, scale, spacing). Return one string for each supplied value.
import pyqtgraph as pg
class MonthAxis(pg.AxisItem):
def tickStrings(self, values, scale, spacing):
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
return [months[int(value) % 12] for value in values]This example is suitable only when integer-like tick values represent month indices. It does not account for year boundaries. For real dates, format the actual date representation or use DateAxisItem. In log mode, PyQtGraph routes label generation through logTickStrings(), which is also an override point in the AxisItem API.
Format actual dates with DateAxisItem
If the x coordinates are Unix timestamps, replace the plot’s bottom axis with a DateAxisItem. It formats date labels according to the time density currently visible, avoiding a manually maintained mapping of timestamp positions to strings.
import pyqtgraph as pg
plot = pg.PlotWidget()
axis = pg.DateAxisItem(orientation='bottom')
plot.setAxisItems({'bottom': axis})
# x_values must contain Unix timestamps.
plot.plot(x_values, y_values)The axis expects timestamp-valued x data. Do not pass ordinal month positions such as 0, 1, and 2 as though they were timestamps; use explicit ticks or a custom mapping for those values. The API also accepts an optional utcOffset. Choose timezone handling deliberately for your data and intended display; the concise API reference documents the parameter but does not spell out all conversion rules. See the DateAxisItem API reference and its source documentation.
Prevent labels from being clipped or crowded
Month names and formatted dates take more room than numeric ticks. If text overlaps or is cut off, inspect the axis style and the plot at the window size and font used by your application. AxisItem.setStyle() documents controls including autoExpandTextSpace, autoReduceTextSpace, hideOverlappingLabels, and tick-text width and height settings. Horizontal axes hide labels extending beyond the axis geometry by default; vertical axes permit extension by default. These options are documented in the AxisItem API reference.
Check the installed PyQtGraph version
The current online API documentation identifies itself as version 0.15.0.dev0. Since API details can differ by installed release, check the documentation and behavior for the version used by your application before relying on a version-specific detail.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
