We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

The Tkinter Label Widget

The Label widget is a standard Tkinter widget used to display a text or image on the screen. The label can only display text in a single font, but the text may span more than one line. In addition, one of the characters can be underlined, for example to mark a keyboard shortcut.

When to use the Label Widget

Labels are used to display texts and images. The label widget uses double buffering, so you can update the contents at any time, without annoying flicker.

To display data that the user can manipulate in place, it’s probably easier to use the Canvas widget.

Patterns

To use a label, you just have to specify what to display in it (this can be text, a bitmap, or an image):

from Tkinter import *

master = Tk()

w = Label(master, text="Hello, world!")
w.pack()

mainloop()


If you don’t specify a size, the label is made just large enough to hold its contents. You can also use the height and width options to explicitly set the size. If you display text in the label, these options define the size of the label in text units. If you display bitmaps or images instead, they define the size in pixels (or other screen units). See the Button description for an example how to specify the size in pixels also for text labels.

You can specify which color to use for the label with the foreground (or fg) and background (or bg) options. You can also choose which font to use in the label (the following example uses Tk 8.0 font descriptors). Use colors and fonts sparingly; unless you have a good reason to do otherwise, you should stick to the default values.

w = Label(master, text="Rouge", fg="red")
w = Label(master, text="Helvetica", font=("Helvetica", 16))

Labels can display multiple lines of text. You can use newlines or use the wraplength option to make the label wrap text by itself. When wrapping text, you might wish to use the anchor and justify options to make things look exactly as you wish. An example:

w = Label(master, text=longtext, anchor=W, justify=LEFT)

You can associate a Tkinter variable with a label. When the contents of the variable changes, the label is automatically updated:

v = StringVar()
Label(master, textvariable=v).pack()

v.set("New Text!")

You can use the label to display PhotoImage and BitmapImage objects. When doing this, make sure you keep a reference to the image object, to prevent it from being garbage collected by Python’s memory allocator. You can use a global variable or an instance attribute, or easier, just add an attribute to the widget instance:

photo = PhotoImage(file="icon.gif")
w = Label(parent, image=photo)
w.photo = photo
w.pack()

Reference

Label(master=None, **options) (class) [#]

Display a single line of text, or an image.

master
Parent widget.
**options
Widget options. See the description of the config method for a list of available options.

config(**options) [#]

Modifies one or more widget options. If no options are given, the method returns a dictionary containing all current option values.

**options
Widget options.
activebackground=
What background color to use when the label is active (set with the state option). The default is platform specific. (the option database name is activeBackground, the class is Foreground)
activeforeground=
What foreground color to use when the label is active. The default is platform specific. (activeForeground/Background)
anchor=
Controls where in the label the text (or image) should be located. Use one of N, NE, E, SE, S, SW, W, NW, or CENTER. Default is CENTER. (anchor/Anchor)
background=
The background color. The default is platform specific. (background/Background)
bg=
Same as background.
bitmap=
The bitmap to display in the widget. If the image option is given, this option is ignored. (bitmap/Bitmap)
borderwidth=
The width of the label border. The default is system specific, but is usually one or two pixels. (borderWidth/BorderWidth)
bd=
Same as borderwidth.
compound=
Controls how to combine text and image in the label. By default, if an image or bitmap is given, it is drawn instead of the text. If this option is set to CENTER, the text is drawn on top of the image. If this option is set to one of BOTTOM, LEFT, RIGHT, or TOP, the image is drawn besides the text (use BOTTOM to draw the image under the text, etc.). Default is NONE. (compound/Compound)
cursor=
What cursor to show when the mouse is moved over the label. The default is to use the standard cursor. (cursor/Cursor)
disabledforeground=
What foreground color to use when the label is disabled. The default is system specific. (disabledForeground/DisabledForeground)
font=
The font to use in the label. The label can only contain text in single font. The default is system specific. (font/Font)
foreground=
The label color, used for for text and bitmap labels. The default is system specific. (foreground/Foreground)
fg=
Same as foreground.
height=
The height of the label. If the label displays text, the size is given in text units. If the label displays an image, the size is given in pixels (or screen units). If the size is set to 0, or omitted, it is calculated based on the label contents. (height/Height)
highlightbackground=
What color to use for the highlight border when the widget does not have focus. The default is system specific, but usually the same as the standard background color. (highlightBackground/HighlightBackground)
highlightcolor=
What color to use for the highlight border when the widget has focus. The default is system specific. (highlightColor/HighlightColor)
highlightthickness=
The width of the highlight border. The default is 0 (no highlight border). (highlightThickness/HighlightThickness)
image=
The image to display in the widget. The value should be a PhotoImage, BitmapImage, or a compatible object. If specified, this takes precedence over the text and bitmap options. (image/Image)
justify=
Defines how to align multiple lines of text. Use LEFT, RIGHT, or CENTER. Note that to position the text inside the widget, use the anchor option. Default is CENTER. (justify/Justify)
padx=
Extra horizontal padding to add around the text. The default is 1 pixel. (padX/Pad)
pady=
Extra vertical padding to add around the text. The default is 1 pixel. (padY/Pad)
relief=
Border decoration. The default is FLAT. Other possible values are SUNKEN, RAISED, GROOVE, and RIDGE. (relief/Relief)
state=
Label state. This option controls how the label is rendered. The default is NORMAL. Other possible values are ACTIVE and DISABLED. (state/State)
takefocus=
If true, the widget accepts input focus. The default is false. (takeFocus/TakeFocus)
text=
The text to display in the label. The text can contain newlines. If the bitmap or image options are used, this option is ignored. (text/Text)
textvariable=
Associates a Tkinter variable (usually a StringVar) with the label. If the variable is changed, the label text is updated. (textVariable/Variable)
underline=
Used with the text option to indicate that a character should be underlined (e.g. for keyboard shortcuts). Default is -1 (no underline). (underline/Underline)
width=
The width of the label. If the label displays text, the size is given in text units. If the label displays an image, the size is given in pixels (or screen units). If the size is set to 0, or omitted, it is calculated based on the label contents. (width/Width)
wraplength=
Determines when a label’s text should be wrapped into multiple lines. This is given in screen units. Default is 0 (no wrapping). (wrapLength/WrapLength)