Docs · Guide

The turtle library

Type import turtle in the Playground and you get a little pen that walks around a window, drawing a line behind it. Tell it to go forward, turn, change colour, and lift the pen, and you can draw anything from a square to a rainbow spiral. This is the hands-on how-to; the one-line reference for every call is on the Docs page. Every example has a Try it button that drops it into the Playground.

A pen that walks

The turtle starts in the middle of the window, facing right. Two ideas do most of the work: turtle.forward(n) walks n steps and draws a line, and turtle.left(deg) or turtle.right(deg) turns it on the spot by a number of degrees. A square is just "go forward, turn a quarter (90 degrees)", four times.

import turtle

turtle.pensize(3)
turtle.pencolor("teal")

# Forward, then a quarter turn, four times = a square
for side in range(4):
    turtle.forward(120)
    turtle.left(90)

The whole toolkit is just verbs. forward, backward, left, right: you are steering. Change the 120 or the 90 and watch the shape change. Turn by 120 three times and you get a triangle; by 60 six times, a hexagon.

Pen and colour

Change how the line looks with turtle.pencolor(c) and how thick it is with turtle.pensize(n). Any colour name works ("red", "gold"), or a hex code like "#5db8ff". To move without drawing, lift the pen with turtle.penup(), move, then turtle.pendown() to draw again. Paint the whole background with turtle.bgcolor(c).

turtle.pencolor("#5db8ff")   # sky blue line
turtle.pensize(5)            # nice and thick
turtle.penup()               # lift: move without a line
turtle.forward(80)
turtle.pendown()             # down again: back to drawing

Loops make patterns

This is where turtle gets fun. A for loop repeats a move-and-turn, and a tiny turn each time sweeps the drawing around into a pattern. Change one number and the whole picture changes. Here the pen walks a little further and shifts its colour every step, spiralling into a rainbow.

import turtle

turtle.speed(0)              # 0 means "as fast as possible"
turtle.bgcolor("#0b1020")
turtle.pensize(2)

colours = ["#ff5d5d", "#ffb35d", "#ffe95d", "#5dff9e", "#5db8ff", "#b98cff"]
for i in range(120):
    turtle.pencolor(colours[i % len(colours)])
    turtle.forward(i * 2)    # a bit further every time
    turtle.left(59)          # not quite 60, so it spirals

Try turtle.left(60) instead of 59: the ends meet and you get a neat hexagon rosette. The magic is in that one number.

Filling shapes

To colour a shape in, set the fill colour, say begin_fill(), draw the outline, then end_fill() pours the paint. Turning right(144) five times traces a five-pointed star.

import turtle

turtle.pensize(3)
turtle.pencolor("#c0392b")
turtle.fillcolor("gold")

turtle.begin_fill()
for point in range(5):
    turtle.forward(170)
    turtle.right(144)        # the star angle
turtle.end_fill()

turtle.circle(r) draws a circle of radius r. Overlap a ring of them and you get a flower:

import turtle

turtle.speed(0)
turtle.bgcolor("#101826")
turtle.pencolor("#ff7ac6")
turtle.pensize(2)

for petal in range(18):
    turtle.circle(90)        # one circle
    turtle.left(20)          # turn a little, then another

Go anywhere

The centre of the window is (0, 0). Jump the turtle straight to a spot with turtle.goto(x, y) (lift the pen first if you do not want a line), point it in an exact direction with turtle.setheading(deg) (0 is right, 90 is up, 180 left, 270 down), and send it back to the middle with turtle.home().

turtle.penup()
turtle.goto(-100, 50)    # jump, no line
turtle.pendown()
turtle.setheading(90)    # now face straight up
turtle.forward(120)

You can also ask the turtle where it is: turtle.xcor(), turtle.ycor() and turtle.heading(). Handy for "keep going until you reach the edge" style drawings.

Finishing touches

  • turtle.dot(size, colour): stamp a filled dot where the turtle stands, no pen needed.
  • turtle.write("Hi!"): write words at the turtle. Add font=("Arial", 20, "normal") to size them.
  • turtle.speed(n): 1 is slow, 10 is fast, 0 is instant. Great for big patterns.
  • turtle.hideturtle(): hide the arrow for a clean finished picture (showturtle() brings it back).
  • turtle.clear() wipes the drawing but leaves the turtle put; turtle.reset() wipes everything and sends it home.

Tip: a big pattern draws fastest with turtle.speed(0) and turtle.hideturtle() at the top. Add them and the rainbow spiral snaps into place at once.

Now open the Playground, type import turtle, and draw something. Change a number in any example above and see what happens.

Open the Playground Full call reference