A Simple Tutorial for Python's turtle.py Module

Introduction

Turtle graphics is a popular way to teach programming. A drawing pen cursor (called the "turtle") can be programmed to move around the screen. The turtle draws lines as it moves. You can write programs that draw beautiful shapes and learn to program at the same time.

This tutorial only explains Python's turtle.py module. It does not explain the Python programming language. This guide assumes you know basic Python concepts: variables, operators, for loops, function calls, and random numbers. This guide assumes you have Python installed and are writing Python code using IDLE, Mu, Visual Studio Code, or some other code editor.

Quickstart

Let's write a program that draws a square. In a new file enter the following Python code:

from turtle import *

forward(100)
left(90)
forward(100)
left(90)
forward(100)
left(90)
forward(100)

When you run this program, a new window will appear and you will see the an arrow cursor. This arrow is the drawing turtle. The program tells the turtle where to move, and the turtle draws lines while moving:

The steps given to the program are:

Move forward 100 steps. (In the beginning, the turtle is facing to the right.)
Turn 90 degrees to the left.
Move forward 100 steps.
Turn 90 degrees to the left.
Move forward 100 steps.
Turn 90 degrees to the left.
Move forward 100 steps. (The turtle has ended up where it started.)

With these seven steps, the turtle draws a square. The from turtle import * is an instruction needed at the beginning of all of your turtle programs. It imports the turtle module so you can do the turtle instructions.

There are many instructions like left() and forward(). These instructions are called functions. This tutorial explains many of the functions in the turtle module. When you learn more of these functions, you will be able to draw many different shapes and beautiful pictures!

Examples

This is a square spiral program:

from turtle import *
for i in range(500): # this "for" loop will repeat these functions 500 times
    forward(i)
    left(91)

This is a hexagon spiral program:

from turtle import *
colors = ['red', 'purple', 'blue', 'green', 'yellow', 'orange']
for x in range(360):
    pencolor(colors[x % 6])
    width(x / 100 + 1)
    forward(x)
    left(59)

This is a program that draws blue flowers:

from turtle import *
import random

for n in range(60):
    penup()
    goto(random.randint(-400, 400), random.randint(-400, 400))
    pendown()

    red_amount   = random.randint( 0,  30) / 100.0
    blue_amount  = random.randint(50, 100) / 100.0
    green_amount = random.randint( 0,  30) / 100.0
    pencolor((red_amount, green_amount, blue_amount))

    circle_size = random.randint(10, 40)
    pensize(random.randint(1, 5))

    for i in range(6):
        circle(circle_size)
        left(60)

Moving

By calling these functions, the turtle can be made to move around the screen. Imagine the turtle holding a pen down on the ground and drawing a line as it moves around.

The turtle's position is two numbers: the X coordinate and Y coordinate. The turtle also

forward(distance)

The forward() function moves the turtle distance number of steps in the current direction. If the pen is down (see pendown() and penup()) a line will be drawn as the turtle moves forward. If distance is a negative number, the turtle will move backwards.

backward(distance)

The backward() function moves the turtle distance number of steps in opposite direction the current direction. If the pen is down (see pendown() and penup()) a line will be drawn as the turtle moves backward. If distance is a negative number, the turtle will move forward.

right(angle)

The right() function will change the current direction clockwise by angle degrees. If you imagine being above the turtle looking down, the turtle turning right looks like it is turning clockwise. The turtle will not move; it will only change the direction it is facing.

This example moves the turtle forward, then turns right by 90 degrees, then moves forward again:

This example moves the turtle forward, then turns left by 90 degrees, then moves forward again:

from turtle import *
forward(100)
right(90)
forward(100)

left(angle)

The left() function will change the current direction counter-clockwise or anti-clockwise by angle degrees. If you imagine being above the turtle looking down, the turtle turning left looks like it is turning counter-clockwise or anti-clockwise. The turtle will not move; it will only change the direction it is facing.

This example moves the turtle forward, then turns left by 90 degrees, then moves forward again:

from turtle import *
forward(100)
left(90)
forward(100)

goto(x, y)

The goto() function will immediately move the turtle to the given x and y coordinates. If the pen is down (see pendown() and penup()) a line will be drawn from the previous coordinates to the new coordinates.

This example moves the to several x and y coordinates while drawing a line behind it:

from turtle import *

goto(50, 50)
goto(-50, 50)
goto(100, -50)
goto(-50, -50)

setx(x)

The goto() function will immediately move the turtle to the given x coordinate. The turtle's y coordinate will stay the same. If the pen is down (see pendown() and penup()) a line will be drawn from the previous coordinates to the new coordinates.

sety(y)

The goto() function will immediately move the turtle to the given y coordinate. The turtle's x coordinate will stay the same. If the pen is down (see pendown() and penup()) a line will be drawn from the previous coordinates to the new coordinates.

setheading(heading)

The setheading() function will change the current direction to the heading angle. If you imagine being above the turtle looking down, the turtle turning left looks like it is turning counter-clockwise or anti-clockwise. The turtle will not move; it will only change the heading it is facing.

from turtle import *

for angle in range(0, 360, 15):
    setheading(angle)
    forward(100)
    write(str(angle) + '°')
    backward(100)

undo()

The undo() function will undo the turtle's last action. It will be as though the last action was never made. For example, if the last action was a call to the forward(100) function, calling undo will move the turtle backwards 100 steps and erase any line that was drawn. The undo() function can be called many times to erase more and more of the turtle

from turtle import *

for i in range(10):
    forward(100)
    left(90)
    forward(10)
    left(90)
    forward(100)
    right(90)
    forward(10)
    right(90)

for i in range(30):
    undo()

home()

The home() function will move the turtle to it's original position at the coordinates (0, 0) and set it's direction to 0 degrees. Calling home() is the same as calling goto(0, 0) and setheading(0). If the pen is down (see pendown() and penup()) a line will be drawn as the turtle moves back home.

from turtle import *

forward(100)
right(90)
forward(100)
home()

Drawing

pendown()

The pendown() function will cause the turtle to draw as it moves around. The line it draws can be set with the pencolor() and pensize() functions.

penup()

The penup() function will cause the turtle to draw as it moves around. The line it draws can be set with the pencolor() and pensize() functions.

pensize(size)

The pensize() function sets the width of the line that the turtle draws as it moves.

pencolor(), pencolor(color), pencolor((red, green, blue)), pencolor(red, green, blue)

The pencolor() function sets the color of the line that the turtle draws. The pencolor() function can be passed a string of the color, such as 'red' or 'black'. Or, the pencolor() function can be passed an "RGB color tuple" (see the Color section).

from turtle import *

pensize(20)
pencolor('red')
forward(50)
pencolor(0, 1.0, 0)
forward(50)
pencolor((0, 0.5, 0.5))
forward(50)

pensize(10)
goto(-400, 50)

for red in range(4):
    for green in range(4):
        for blue in range(4):
            pencolor(red / 4.0, green / 4.0, blue / 4.0)
            forward(10)

clear()

The clear() function will erase all the line drawings on the screen. This function does not move the turtle.

reset()

The reset()) function will erase all the line drawings on the screen and return the turtle to the (0, 0) coordinate and facing 0 degrees. This function does the same thing as calling the clear() and home() function.

Color

Red, green, and blue are the three primary colors of light.

The float value 0.0 represents none of that color. The float value 1.0 represents a full color. So the color red is represented by the RGB color tuple (1.0, 0, 0). The color purple is half-red and half-blue, so it is represented by the RGB color tuple (0.5, 0.0, 0.5). Full red and blue makes pink: (1.0, 0.0, 1.0)

Here are some RGB color tuples:

(0.2, 0.0, 0.0)	(0.2, 0.1, 0.0)	(0.2, 0.2, 0.0)	(0.1, 0.2, 0.0)	(0.0, 0.2, 0.0)	(0.0, 0.2, 0.1)	(0.0, 0.2, 0.2)	(0.0, 0.1, 0.2)	(0.0, 0.0, 0.2)	(0.1, 0.0, 0.2)	(0.2, 0.0, 0.2)	(0.2, 0.0, 0.1)	(0.0, 0.0, 0.0)
(0.4, 0.0, 0.0)	(0.4, 0.2, 0.0)	(0.4, 0.4, 0.0)	(0.2, 0.4, 0.0)	(0.0, 0.4, 0.0)	(0.0, 0.4, 0.2)	(0.0, 0.4, 0.4)	(0.0, 0.2, 0.4)	(0.0, 0.0, 0.4)	(0.2, 0.0, 0.4)	(0.4, 0.0, 0.4)	(0.4, 0.0, 0.2)	(0.13, 0.13, 0.13)
(0.6, 0.0, 0.0)	(0.6, 0.3, 0.0)	(0.6, 0.6, 0.0)	(0.3, 0.6, 0.0)	(0.0, 0.6, 0.0)	(0.0, 0.6, 0.3)	(0.0, 0.6, 0.6)	(0.0, 0.3, 0.6)	(0.0, 0.0, 0.6)	(0.3, 0.0, 0.6)	(0.6, 0.0, 0.6)	(0.6, 0.0, 0.3)	(0.25, 0.25, 0.25)
(0.8, 0.0, 0.0)	(0.8, 0.4, 0.0)	(0.8, 0.8, 0.0)	(0.4, 0.8, 0.0)	(0.0, 0.8, 0.0)	(0.0, 0.8, 0.4)	(0.0, 0.8, 0.8)	(0.0, 0.4, 0.8)	(0.0, 0.0, 0.8)	(0.4, 0.0, 0.8)	(0.8, 0.0, 0.8)	(0.8, 0.0, 0.4)	(0.38, 0.38, 0.38)
(1.0, 0.0, 0.0)	(1.0, 0.5, 0.0)	(1.0, 1.0, 0.0)	(0.5, 1.0, 0.0)	(0.0, 1.0, 0.0)	(0.0, 1.0, 0.5)	(0.0, 1.0, 1.0)	(0.0, 0.5, 1.0)	(0.0, 0.0, 1.0)	(0.5, 0.0, 1.0)	(1.0, 0.0, 1.0)	(1.0, 0.0, 0.5)	(0.5, 0.5, 0.5)
(1.0, 0.2, 0.2)	(1.0, 0.6, 0.2)	(1.0, 1.0, 0.2)	(0.6, 1.0, 0.2)	(0.2, 1.0, 0.2)	(0.2, 1.0, 0.6)	(0.2, 1.0, 1.0)	(0.2, 0.6, 1.0)	(0.2, 0.2, 1.0)	(0.6, 0.2, 1.0)	(1.0, 0.2, 1.0)	(1.0, 0.2, 0.6)	(0.63, 0.63, 0.63)
(1.0, 0.4, 0.4)	(1.0, 0.7, 0.4)	(1.0, 1.0, 0.4)	(0.7, 1.0, 0.4)	(0.4, 1.0, 0.4)	(0.4, 1.0, 0.7)	(0.4, 1.0, 1.0)	(0.4, 0.7, 1.0)	(0.4, 0.4, 1.0)	(0.7, 0.4, 1.0)	(1.0, 0.4, 1.0)	(1.0, 0.4, 0.7)	(0.75, 0.75, 0.75)
(1.0, 0.6, 0.6)	(1.0, 0.8, 0.6)	(1.0, 1.0, 0.6)	(0.8, 1.0, 0.6)	(0.6, 1.0, 0.6)	(0.6, 1.0, 0.8)	(0.6, 1.0, 1.0)	(0.6, 0.8, 1.0)	(0.6, 0.6, 1.0)	(0.8, 0.6, 1.0)	(1.0, 0.6, 1.0)	(1.0, 0.6, 0.8)	(0.88, 0.88, 0.88)
(1.0, 0.8, 0.8)	(1.0, 0.9, 0.8)	(1.0, 1.0, 0.8)	(0.9, 1.0, 0.8)	(0.8, 1.0, 0.8)	(0.8, 1.0, 0.9)	(0.8, 1.0, 1.0)	(0.8, 0.9, 1.0)	(0.8, 0.8, 1.0)	(0.9, 0.8, 1.0)	(1.0, 0.8, 1.0)	(1.0, 0.8, 0.9)	(1.0, 1.0, 1.0)

RGB Color Tuple:

Filling in Shapes

The turtle can draw the outline of a shape and then fill it in with color using the fill functions. The filling process starts when the begin_color() function is called. The turtle can move around as normal. When the end_fill() function is called, the shape the turtle was drawing will be filled with the fill color. The fill color is separate from the pen color.

from turtle import *

fillcolor('purple')
pensize(10)
pencolor('black')
forward(100)

begin_fill()
forward(100)
left(90)
forward(100)
left(90)
forward(100)
left(90)
forward(100)
left(90)
end_fill()

fillcolor(), fillcolor(color), fillcolor((red, green, blue)), fillcolor(red, green, blue)

The fillcolor() function sets the color of the filled in shape when end_fill() is called. The fillcolor() function can be passed a string of the color, such as 'red' or 'black'. Or, the fillcolor() function can be passed an "RGB color tuple" (see the Color section).

begin_fill()

The begin_fill() starts recording the moves that will be the outline of the filled-in shape. The filled-in shape will not be drawn until end_fill() is called.

end_fill()

The end_fill() function will stop recording the moves for the filled-in shape and draw the shape.

Stamping

stamp()

from turtle import *

penup()

for i in range(30, -1, -1):
    stamp()
    left(i)
    forward(20)

clearstamp()

clearstamps()

Animation

tracer()

Turtle Status

position()

towards()

distance()

degrees()

radians()

isdown()

isvisible()

Input

Events

listen()

onkey()

from turtle import *

def up():
    setheading(90)
    forward(100)

def down():
    setheading(270)
    forward(100)

def left():
    setheading(180)
    forward(100)

def right():
    setheading(0)
    forward(100)

listen()

onkey(up, 'Up')
onkey(down, 'Down')
onkey(left, 'Left')
onkey(right, 'Right')

onkey(up, 'w')
onkey(down, 's')
onkey(left, 'a')
onkey(right, 'd')

up, right, down, down, left, left, up

onkeypress()

from turtle import *

def blue_screen():
    bgcolor(0.7, 1.0, 1.0)

def white_screen():
    bgcolor(1.0, 1.0, 1.0)

listen()
onkeypress(blue_screen, 'space')
onkey(white_screen, 'space')

Files

simple_turtle_tutorial.md

Latest commit

History

simple_turtle_tutorial.md

File metadata and controls

A Simple Tutorial for Python's turtle.py Module

Table of Contents

Introduction

Quickstart

Examples

Moving

forward(distance)

backward(distance)

right(angle)

left(angle)

goto(x, y)

setx(x)

sety(y)

setheading(heading)

undo()

home()

Drawing

pendown()

penup()

pensize(size)

pencolor(), pencolor(color), pencolor((red, green, blue)), pencolor(red, green, blue)

clear()

reset()

Color

Filling in Shapes

fillcolor(), fillcolor(color), fillcolor((red, green, blue)), fillcolor(red, green, blue)

begin_fill()

end_fill()

Stamping

stamp()

clearstamp()

clearstamps()

Animation

tracer()

Turtle Status

position()

towards()

distance()

degrees()

radians()

isdown()

isvisible()

Input

Events

listen()

onkey()

onkeypress()

onclick()

ontimer()

done()

exitonclick()

The Turtle

showturtle()

hideturtle()

shape()

The World

bgcolor()

bgpic()

title()

screensize()

window_height()

window_width()

listen()