Python Turtle Background: Color, Hex, RGB and Images

To change the background color in Python turtle, call bgcolor() on the screen:

import turtle

screen = turtle.Screen()
screen.bgcolor("lightblue")     # a name, a hex code, or an RGB tuple

The catch is RGB. Passing (255, 100, 0) raises an error until you switch the color mode, because turtle expects values from 0 to 1 by default.

All the windows and output below are real, on Python 3.12.5, Tk 8.6.

Setting the Python turtle background color

One line changes it, and everything you draw afterwards sits on top:

import turtle

screen = turtle.Screen()
screen.setup(640, 420)

screen.bgcolor("lightblue")        # the whole answer

pen = turtle.Turtle()
pen.pensize(4)
pen.color("#c0392b")
pen.circle(90)

print("background is now:", screen.bgcolor())
turtle.done()

Output:

background is now: lightblue

Set the background before you draw. Changing it later still works, but the screen repaints and any animation you were running restarts visibly.

turtle.bgcolor("lightblue") without a screen object works too. It uses the default screen, which turtle creates for you on first use.

Turtle background color names, hex codes and RGB

Three formats are accepted, and only one of them needs setting up first:

import turtle

screen = turtle.Screen()
screen.setup(400, 300)

print("default background:", screen.bgcolor())
print("default colormode :", screen.colormode())

# a color name
screen.bgcolor("tomato")
print("by name :", screen.bgcolor())

# a hex code, which reads back as floats
screen.bgcolor("#ffcc00")
print("by hex  :", screen.bgcolor())

# RGB numbers from 0 to 255 need the color mode changed first
try:
    screen.bgcolor((255, 100, 0))
except turtle.TurtleGraphicsError as err:
    print("\nRGB 0-255 straight away ->", type(err).__name__ + ":", err)

screen.colormode(255)
screen.bgcolor((255, 100, 0))
print("after colormode(255)    :", screen.bgcolor())
turtle.bye()

Output:

default background: white
default colormode : 1.0
by name : tomato
by hex  : (1.0, 0.8, 0.0)

RGB 0-255 straight away -> TurtleGraphicsError: bad color sequence: (255, 100, 0)
after colormode(255)    : (255.0, 100.0, 0.0)

Format	Example	Notes
Name	bgcolor("lightblue")	Around 140 Tk color names
Hex	bgcolor("#ffcc00")	Always works, reads back as floats
RGB 0–1	bgcolor((1.0, 0.8, 0.0))	The default color mode
RGB 0–255	bgcolor((255, 204, 0))	Needs colormode(255) first

The default colormode is 1.0, so turtle reads a tuple as three fractions. (255, 100, 0) is nonsense in that range, hence the error.

Hex codes sidestep the whole issue. They need no mode change and copy straight out of a design tool.

Using a dark turtle background

Dark backgrounds make bright drawings stand out, which is worth knowing for anything you’re screenshotting:

import turtle

screen = turtle.Screen()
screen.setup(680, 420)
screen.bgcolor("#1b2838")          # a dark background

pen = turtle.Turtle()
pen.speed(0)
pen.pensize(3)

# light colors read well on a dark background
for i, color in enumerate(("#f5c518", "#4fc3f7", "#81c784", "#ff8a65")):
    pen.penup()
    pen.goto(-240 + i * 160, -60)
    pen.pendown()
    pen.color(color)
    pen.begin_fill()
    pen.circle(60)
    pen.end_fill()

print("background:", screen.bgcolor())
turtle.done()

Output:

background: (0.10588235294117647, 0.1568627450980392, 0.2196078431372549)

Pick the background first and then the pen colors. Doing it the other way round usually means re-picking everything.

For the shapes themselves, see drawing circles with turtle.

Setting a Python turtle background image

bgpic() loads a picture behind your drawing. The format rules are more generous than most guides claim:

import turtle
from PIL import Image

# make three test pictures so this example stands on its own
Image.new("RGB", (300, 200), "#4477aa").save("bg.png")
Image.new("RGB", (300, 200), "#44aa77").save("bg.gif")
Image.new("RGB", (300, 200), "#aa7744").save("bg.jpg")

screen = turtle.Screen()
screen.setup(400, 300)

print("bgpic with nothing set:", screen.bgpic())
print()

for filename in ("bg.gif", "bg.png", "bg.jpg"):
    try:
        screen.bgpic(filename)
        print(f"{filename:<8} -> loaded")
    except Exception as err:
        print(f"{filename:<8} -> {type(err).__name__}: {str(err)[:55]}")

screen.bgpic("nopic")
print()
print("after clearing:", screen.bgpic())
turtle.bye()

Output:

bgpic with nothing set: nopic

bg.gif   -> loaded
bg.png   -> loaded
bg.jpg   -> TclError: couldn't recognize data in image file "bg.jpg"

after clearing: nopic

The old advice that bgpic only accepts GIF is out of date. Tk 8.6 ships with modern Python and reads PNG as well.

JPEG still fails, with couldn't recognize data in image file. Convert it to PNG first, which Pillow does in two lines.

• The image is not scaled. It is drawn at its natural size, centred on the screen.
• Size the window to the picture with screen.setup(width, height).
• screen.bgpic("nopic") removes it again.
• screen.bgpic() with no argument returns the current filename, or "nopic".

Reading and resetting the background

Called with no argument, bgcolor() reads the value rather than setting it:

import turtle

screen = turtle.Screen()
screen.setup(400, 300)

screen.bgcolor("navy")
print("set to     :", screen.bgcolor())

# calling it with no argument READS the value instead of setting it
current = screen.bgcolor()
print("read back  :", current)

# back to the default
screen.bgcolor("white")
print("reset to   :", screen.bgcolor())

print()
print("screen.reset() clears the drawing but keeps the background")
print("screen.clear() resets the background to white as well")
turtle.bye()

Output:

set to     : navy
read back  : navy
reset to   : white

screen.reset() clears the drawing but keeps the background
screen.clear() resets the background to white as well

That getter form is handy for restoring a color after a temporary change, such as flashing the screen.

Watch the difference between the two clearing methods. screen.reset() keeps your background, while screen.clear() puts it back to white.

Common turtle background problems

Symptom	Cause	Fix
bad color sequence	RGB 0–255 in the default mode	screen.colormode(255)
couldn't recognize data	JPEG passed to bgpic	Convert to PNG or GIF
Image only partly visible	bgpic does not scale	Match the window to the image
Background back to white	screen.clear() was called	Use screen.reset()
Window closes instantly	No turtle.done()	Add it at the end
Terminator error	Drawing after bye()	Create a new screen

More Python turtle guides:

• Draw a circle with Python turtle
• Python turtle colors
• Hide the turtle
• Random values with turtle
• Python turtle interview questions
• When a Python plot window does not appear

Frequently asked questions