24.1. turtle — Turtle graphics

Note

The turtle module that comes with Pythonista is not 100% compatible with the standard library version because it’s based on the ui module rather than Tkinter (which isn’t available in Pythonista). It should work just fine for learning, but some advanced features (like mouse/keyboard interaction) are not implemented. For typical (educational) use cases, this should not be a problem. This documentation page has been edited to remove references to features that are not available in Pythonista, but the rest is mostly unchanged.

24.1.1. Introduction

Turtle graphics is a popular way for introducing programming to kids. It was part of the original Logo programming language developed by Wally Feurzig and Seymour Papert in 1966.

Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an import turtle, give it the command turtle.forward(15), and it moves (on-screen!) 15 pixels in the direction it is facing, drawing a line as it moves. Give it the command turtle.right(25), and it rotates in-place 25 degrees clockwise.

By combining together these and similar commands, intricate shapes and pictures can easily be drawn.

The turtle module is an extended reimplementation of the same-named module from the Python standard distribution up to version Python 2.5.

The turtle module provides turtle graphics primitives, in both object-oriented and procedure-oriented ways.

The procedural interface provides functions which are derived from the methods of the classes Screen and Turtle. They have the same names as the corresponding methods. A screen object is automatically created whenever a function derived from a Screen method is called. An (unnamed) turtle object is automatically created whenever any of the functions derived from a Turtle method is called.

To use multiple turtles on a screen one has to use the object-oriented interface.

Note

In the following documentation the argument list for functions is given. Methods, of course, have the additional first argument self which is omitted here.

24.1.2. Overview of available Turtle and Screen methods

24.1.2.1. Turtle methods

Turtle motion
Move and draw
Tell Turtle’s state
Setting and measurement
Pen control
Drawing state
Color control
Filling
More drawing control
Turtle state
Visibility
Appearance
shape()
resizemode()
shapesize() | turtlesize()
shearfactor()
settiltangle()
tiltangle()
tilt()
shapetransform()
get_shapepoly()
Using events
onclick()
onrelease()
ondrag()
Special Turtle methods
begin_poly()
end_poly()
get_poly()
setundobuffer()
undobufferentries()

24.1.2.2. Methods of TurtleScreen/Screen

Window control
bgcolor()
bgpic()
clear() | clearscreen()
reset() | resetscreen()
screensize()
setworldcoordinates()
Animation control
update()
Using screen events
listen()
onkey() | onkeyrelease()
onkeypress()
onclick() | onscreenclick()
ontimer()
mainloop() | done()
Settings and special methods
mode()
getcanvas()
getshapes()
register_shape() | addshape()
Input methods
Methods specific to Screen
bye()
exitonclick()

24.1.3. Methods of Turtle and corresponding functions

Most of the examples in this section refer to a Turtle instance called turtle.

24.1.3.1. Turtle motion

turtle.forward(distance)
turtle.fd(distance)
Parameters:distance – a number (integer or float)

Move the turtle forward by the specified distance, in the direction the turtle is headed.

>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)
turtle.back(distance)
turtle.bk(distance)
turtle.backward(distance)
Parameters:distance – a number

Move the turtle backward by distance, opposite to the direction the turtle is headed. Do not change the turtle’s heading.

>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)
turtle.right(angle)
turtle.rt(angle)
Parameters:angle – a number (integer or float)

Turn turtle right by angle units. (Units are by default degrees, but can be set via the degrees() and radians() functions.) Angle orientation depends on the turtle mode, see mode().

>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0
turtle.left(angle)
turtle.lt(angle)
Parameters:angle – a number (integer or float)

Turn turtle left by angle units. (Units are by default degrees, but can be set via the degrees() and radians() functions.) Angle orientation depends on the turtle mode, see mode().

>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0
turtle.goto(x, y=None)
turtle.setpos(x, y=None)
turtle.setposition(x, y=None)
Parameters:
  • x – a number or a pair/vector of numbers
  • y – a number or None

If y is None, x must be a pair of coordinates or a Vec2D (e.g. as returned by pos()).

Move turtle to an absolute position. If the pen is down, draw line. Do not change the turtle’s orientation.

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)
turtle.setx(x)
Parameters:x – a number (integer or float)

Set the turtle’s first coordinate to x, leave second coordinate unchanged.

>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)
turtle.sety(y)
Parameters:y – a number (integer or float)

Set the turtle’s second coordinate to y, leave first coordinate unchanged.

>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)
turtle.setheading(to_angle)
turtle.seth(to_angle)
Parameters:to_angle – a number (integer or float)

Set the orientation of the turtle to to_angle. Here are some common directions in degrees:

standard mode logo mode
0 - east 0 - north
90 - north 90 - east
180 - west 180 - south
270 - south 270 - west
>>> turtle.setheading(90)
>>> turtle.heading()
90.0
turtle.home()

Move turtle to the origin – coordinates (0,0) – and set its heading to its start-orientation (which depends on the mode, see mode()).

>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
turtle.circle(radius, extent=None, steps=None)
Parameters:
  • radius – a number
  • extent – a number (or None)
  • steps – an integer (or None)

Draw a circle with given radius. The center is radius units left of the turtle; extent – an angle – determines which part of the circle is drawn. If extent is not given, draw the entire circle. If extent is not a full circle, one endpoint of the arc is the current pen position. Draw the arc in counterclockwise direction if radius is positive, otherwise in clockwise direction. Finally the direction of the turtle is changed by the amount of extent.

As the circle is approximated by an inscribed regular polygon, steps determines the number of steps to use. If not given, it will be calculated automatically. May be used to draw regular polygons.

>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0
turtle.dot(size=None, *color)
Parameters:
  • size – an integer >= 1 (if given)
  • color – a colorstring or a numeric color tuple

Draw a circular dot with diameter size, using color. If size is not given, the maximum of pensize+4 and 2*pensize is used.

>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0
turtle.speed(speed=None)
Parameters:speed – an integer in the range 0..10 or a speedstring (see below)

Set the turtle’s speed to an integer value in the range 0..10. If no argument is given, return current speed.

If input is a number greater than 10 or smaller than 0.5, speed is set to 0. Speedstrings are mapped to speedvalues as follows:

  • “fastest”: 0
  • “fast”: 10
  • “normal”: 6
  • “slow”: 3
  • “slowest”: 1

Speeds from 1 to 10 enforce increasingly faster animation of line drawing and turtle turning.

Attention: speed = 0 means that no animation takes place. forward/back makes turtle jump and likewise left/right make the turtle turn instantly.

>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9

24.1.3.2. Tell Turtle’s state

turtle.position()
turtle.pos()

Return the turtle’s current location (x,y) (as a Vec2D vector).

>>> turtle.pos()
(440.00,-0.00)
turtle.towards(x, y=None)
Parameters:
  • x – a number or a pair/vector of numbers or a turtle instance
  • y – a number if x is a number, else None

Return the angle between the line from turtle position to position specified by (x,y), the vector or the other turtle. This depends on the turtle’s start orientation which depends on the mode - “standard”/”world” or “logo”).

>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0
turtle.xcor()

Return the turtle’s x coordinate.

>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876
turtle.ycor()

Return the turtle’s y coordinate.

>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254
turtle.heading()

Return the turtle’s current heading (value depends on the turtle mode, see mode()).

>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0
turtle.distance(x, y=None)
Parameters:
  • x – a number or a pair/vector of numbers or a turtle instance
  • y – a number if x is a number, else None

Return the distance from the turtle to (x,y), the given vector, or the given other turtle, in turtle step units.

>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0

24.1.3.3. Settings for measurement

turtle.degrees(fullcircle=360.0)
Parameters:fullcircle – a number

Set angle measurement units, i.e. set number of “degrees” for a full circle. Default value is 360 degrees.

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0

Change angle measurement unit to grad (also known as gon,
grade, or gradian and equals 1/100-th of the right angle.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0
turtle.radians()

Set the angle measurement units to radians. Equivalent to degrees(2*math.pi).

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966

24.1.3.4. Pen control

24.1.3.4.1. Drawing state

turtle.pendown()
turtle.pd()
turtle.down()

Pull the pen down – drawing when moving.

turtle.penup()
turtle.pu()
turtle.up()

Pull the pen up – no drawing when moving.

turtle.pensize(width=None)
turtle.width(width=None)
Parameters:width – a positive number

Set the line thickness to width or return it. If resizemode is set to “auto” and turtleshape is a polygon, that polygon is drawn with the same line thickness. If no argument is given, the current pensize is returned.

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn
turtle.pen(pen=None, **pendict)
Parameters:
  • pen – a dictionary with some or all of the below listed keys
  • pendict – one or more keyword-arguments with the below listed keys as keywords

Return or set the pen’s attributes in a “pen-dictionary” with the following key/value pairs:

  • “shown”: True/False
  • “pendown”: True/False
  • “pencolor”: color-string or color-tuple
  • “fillcolor”: color-string or color-tuple
  • “pensize”: positive number
  • “speed”: number in range 0..10
  • “resizemode”: “auto” or “user” or “noresize”
  • “stretchfactor”: (positive number, positive number)
  • “outline”: positive number
  • “tilt”: number

Note

resizemode, outline, tilt, and stretchfactor are not supported in Pythonista.

This dictionary can be used as argument for a subsequent call to pen() to restore the former pen-state. Moreover one or more of these attributes can be provided as keyword-arguments. This can be used to set several pen attributes in one statement.

>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]
turtle.isdown()

Return True if pen is down, False if it’s up.

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True

24.1.3.4.2. Color control

turtle.pencolor(*args)

Return or set the pencolor.

Four input formats are allowed:

pencolor()
Return the current pencolor as color specification string or as a tuple (see example). May be used as input to another color/pencolor/fillcolor call.
pencolor(colorstring)
Set pencolor to colorstring, which is a Tk color specification string, such as "red", "yellow", or "#33cc8c".
pencolor((r, g, b))
Set pencolor to the RGB color represented by the tuple of r, g, and b. Each of r, g, and b must be in the range 0..colormode, where colormode is either 1.0 or 255 (see colormode()).
pencolor(r, g, b)
Set pencolor to the RGB color represented by r, g, and b. Each of r, g, and b must be in the range 0..colormode.

If turtleshape is a polygon, the outline of that polygon is drawn with the newly set pencolor.

>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51.0, 204.0, 140.0)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
turtle.fillcolor(*args)

Return or set the fillcolor.

Four input formats are allowed:

fillcolor()
Return the current fillcolor as color specification string, possibly in tuple format (see example). May be used as input to another color/pencolor/fillcolor call.
fillcolor(colorstring)
Set fillcolor to colorstring, which is a Tk color specification string, such as "red", "yellow", or "#33cc8c".
fillcolor((r, g, b))
Set fillcolor to the RGB color represented by the tuple of r, g, and b. Each of r, g, and b must be in the range 0..colormode, where colormode is either 1.0 or 255 (see colormode()).
fillcolor(r, g, b)
Set fillcolor to the RGB color represented by r, g, and b. Each of r, g, and b must be in the range 0..colormode.

If turtleshape is a polygon, the interior of that polygon is drawn with the newly set fillcolor.

>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> col = turtle.pencolor()
>>> col
(50.0, 193.0, 143.0)
>>> turtle.fillcolor(col)
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)
turtle.color(*args)

Return or set pencolor and fillcolor.

Several input formats are allowed. They use 0 to 3 arguments as follows:

color()
Return the current pencolor and the current fillcolor as a pair of color specification strings or tuples as returned by pencolor() and fillcolor().
color(colorstring), color((r,g,b)), color(r,g,b)
Inputs as in pencolor(), set both, fillcolor and pencolor, to the given value.
color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))
Equivalent to pencolor(colorstring1) and fillcolor(colorstring2) and analogously if the other input format is used.

If turtleshape is a polygon, outline and interior of that polygon is drawn with the newly set colors.

>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))

See also: colormode().

24.1.3.4.3. Filling

turtle.filling()

Return fillstate (True if filling, False else).

>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)
turtle.begin_fill()

To be called just before drawing a shape to be filled.

turtle.end_fill()

Fill the shape drawn after the last call to begin_fill().

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

24.1.3.4.4. More drawing control

turtle.reset()

Delete the turtle’s drawings from the screen, re-center the turtle and set variables to the default values.

>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
turtle.clear()

Delete the turtle’s drawings from the screen. Do not move turtle. State and position of the turtle as well as drawings of other turtles are not affected.

turtle.write(arg, move=False, align="left", font=("Arial", 8, "normal"))
Parameters:
  • arg – object to be written to the TurtleScreen
  • move – True/False
  • align – one of the strings “left”, “center” or right”
  • font – a triple (fontname, fontsize, fonttype)

Note

The align and font arguments are not supported in Pythonista.

Write text - the string representation of arg - at the current turtle position according to align (“left”, “center” or right”) and with the given font. If move is true, the pen is moved to the bottom-right corner of the text. By default, move is False.

>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)

24.1.3.5. Turtle state

24.1.3.5.1. Visibility

turtle.hideturtle()
turtle.ht()

Make the turtle invisible. It’s a good idea to do this while you’re in the middle of doing some complex drawing, because hiding the turtle speeds up the drawing observably.

>>> turtle.hideturtle()
turtle.showturtle()
turtle.st()

Make the turtle visible.

>>> turtle.showturtle()
turtle.isvisible()

Return True if the Turtle is shown, False if it’s hidden.

>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True

24.1.3.6. Special Turtle methods

turtle.clone()

Create and return a clone of the turtle with same position, heading and turtle properties.

>>> mick = Turtle()
>>> joe = mick.clone()
turtle.getturtle()
turtle.getpen()

Return the Turtle object itself. Only reasonable use: as a function to return the “anonymous turtle”:

>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>
turtle.getscreen()

Return the TurtleScreen object the turtle is drawing on. TurtleScreen methods can then be called for that object.

>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")

24.1.3.7. Animation control

turtle.delay(delay=None)
Parameters:delay – positive integer

Set or return the drawing delay in milliseconds. (This is approximately the time interval between two consecutive canvas updates.) The longer the drawing delay, the slower the animation.

Optional argument:

>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
turtle.tracer(n=None, delay=None)
Parameters:
  • n – nonnegative integer
  • delay – nonnegative integer

Turn turtle animation on/off and set delay for update drawings. If n is given, only each n-th regular screen update is really performed. (Can be used to accelerate the drawing of complex graphics.) When called without arguments, returns the currently stored value of n. Second argument sets delay value (see delay()).

>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2

See also the RawTurtle/Turtle method speed().

24.1.3.8. Input methods

turtle.textinput(title, prompt)
Parameters:
  • title – string
  • prompt – string

Pop up a dialog window for input of a string. Parameter title is the title of the dialog window, propmt is a text mostly describing what information to input. Return the string input. If the dialog is canceled, return None.

>>> screen.textinput("NIM", "Name of first player:")
turtle.numinput(title, prompt, default=None, minval=None, maxval=None)
Parameters:
  • title – string
  • prompt – string
  • default – number (optional)
  • minval – number (optional)
  • maxval – number (optional)

Pop up a dialog window for input of a number. title is the title of the dialog window, prompt is a text mostly describing what numerical information to input. default: default value, minval: minimum value for input, maxval: maximum value for input The number input must be in the range minval .. maxval if these are given. If not, a hint is issued and the dialog remains open for correction. Return the number input. If the dialog is canceled, return None.

>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)

24.1.3.9. Settings and special methods

turtle.colormode(cmode=None)
Parameters:cmode – one of the values 1.0 or 255

Return the colormode or set it to 1.0 or 255. Subsequently r, g, b values of color triples have to be in the range 0..cmode.

>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
     ...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)
turtle.turtles()

Return the list of turtles on the screen.

>>> for turtle in screen.turtles():
...     turtle.color("red")
turtle.window_height()

Return the height of the turtle window.

>>> screen.window_height()
480
turtle.window_width()

Return the width of the turtle window.

>>> screen.window_width()
640

24.1.3.10. Methods specific to Screen, not inherited from TurtleScreen

turtle.setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"])

Set the size and position of the main window. Default values of arguments are stored in the configuration dictionary and can be changed via a turtle.cfg file.

Parameters:
  • width – if an integer, a size in pixels, if a float, a fraction of the screen; default is 50% of screen
  • height – if an integer, the height in pixels, if a float, a fraction of the screen; default is 75% of screen
  • startx – if positive, starting position in pixels from the left edge of the screen, if negative from the right edge, if None, center window horizontally
  • starty – if positive, starting position in pixels from the top edge of the screen, if negative from the bottom edge, if None, center window vertically
>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # sets window to 75% of screen by 50% of screen and centers
turtle.title(titlestring)
Parameters:titlestring – a string that is shown in the titlebar of the turtle graphics window

Set title of turtle window to titlestring.

>>> screen.title("Welcome to the turtle zoo!")

24.1.4. Public classes

class turtle.Turtle

Subclass of RawTurtle, has the same interface but draws on a default Screen object created automatically when needed for the first time.

class turtle.Vec2D(x, y)

A two-dimensional vector class, used as a helper class for implementing turtle graphics. May be useful for turtle graphics programs too. Derived from tuple, so a vector is a tuple!

Provides (for a, b vectors, k number):

  • a + b vector addition
  • a - b vector subtraction
  • a * b inner product
  • k * a and a * k multiplication with scalar
  • abs(a) absolute value of a
  • a.rotate(angle) rotation