Quick Reference Pages

Turtle Reference

The turtle built-in module is used for drawing graphics in Python. turtleBeads.py is a custom module that adds a few commands to easily draw certain shapes centered on the current turtle position, like circles, ellipses, and polygons. This page covers the core commands from both modules and briefly describes how to use them. If you need more details, remember that you can get help for any Python function by calling the built-in help function, for example, you could get help for the turtle penup command by running:


You can download the latest version of turtleBeads.py at this link:


Getting Started

To draw with turtle graphics, you will need to import the built-in turtle module. To do this, add a line of code at the top of your file that looks like this:

from turtle import *

The '*' here means "everything," and this style of import makes the functions in the turtle module directly available.

If you also want to use turtleBeads functions, you should add:

from turtleBeads import *

to the top of your file as well. Make sure the turtleBeads.py file is in the same directory as the file that you are writing your code in, otherwise Python won't be able to import it and you will get an error.


Turtle Functions
Basic Movement:
Function Effect Example(s)
fd / forward Move the turtle forward. fd(100)
bk / back / backward Move the turtle backward. bk(100)
lt / left and rt / right Turn the turtle left or right (in degrees). lt(90)
circle Moves the turtle forward in an arc curving to the left. Two arguments specify radius and how far around the circle to go (in degrees). circle(100) circle(-50, 90)
speed Sets how fast the turtle moves. 1 is slowest, 10 is fastest, and 0 makes the turtle jump instantly instead of moving (which is even faster than speed 10). See also: noTrace. speed(3)
Absolute Movement:
Function Effect Example(s)
seth / setheading Sets the turtle's direction. 0 is due East and positive headings are counterclockwise (so 90 is North). setheading(180)
setpos / setposition / goto / setx / sety Move the turtle from its current position to a new absolute position. setx and sety change either the x or y coordinate without affecting the other. The turtle will still draw while moving unless the pen is retracted. (0, 0) is in the center of the window, +x is to the East, and +y is to the North. setpos(100, 50) sety(0)
Pen Control:
Function Effect Example(s)
pu / penup Retracts the pen, so that the turtle no longer draws as it moves. penup()
pd / pendown Extends the pen, so that the turtle draws as it moves. Pen is extended when the program begins. pendown()
pencolor Sets the color of the pen by name or using red, green, and blue values between 0 and 1. For color names, refer to color charts linked from the quick reference page. pencolor("Blue") pencolor(0,0.3,0.7)
pensize Sets the size of the pen. pensize(3)
Filling Shapes:
Function Effect Example(s)
begin_fill / end_fill Call begin_fill when the turtle is in position to draw a shape, and end_fill once the shape is complete. The region enclosed by the turtle between these two calls will be filled with the current fill color when the end_fill happens.
fillcolor Sets the color to be used when end_fill is called. Accepts same colors as pencolor. fillcolor("Forest Green") fillcolor(0,0.4,0)
color Can be used to set pen and fill color at once. With two arguments, sets pen and fill color to different values. color("Peach Puff") color("Misty Rose", "Lavender")
Function Effect Example(s)
write Use drawText instead. Writes text to the screen, North of the current turtle position (cannot be rotated). Accepts optional arguments to specify whether to move the turtle, how to align the text, and what font to use. write("Test") write("Test", True, "left", ("Arial", 12, "bold))
Function Effect Example(s)
pos / position / xcor / ycor pos and position return the current position of the turtle as a pair of x and y coordinates. xcor and ycor return the individual x- and y-coordinates as numbers if you need to do math with them. print(position()) x = xcor()
heading heading returns the current direction that the turtle is facing, in degrees. 0 is due east, and 90 is north. h = heading()
towards towards returns the direction that the turtle would have to point in (for example by using seth) in order to move towards a specific position.
t = towards(30, 40)
distance distance returns the distance between the current position and the given x/y position.
dist = distance(50, 50)
angle = towards(50, 50)
Function Effect Example(s)
title Sets the window title for the turtle window. title("Drawing")
bgcolor Sets the background color of the turtle window. bgcolor("Light Sky Blue")
reset Clears everything that's been drawn and puts the turtle back in the middle of the window facing East. Does not reset the title or background color. reset()
Turtle Beads Functions
Function Effect Example(s)
realign Shortcut for setheading(0). realign()
teleport Retracts the pen, uses setpos to move to the given x/y position, and then extends the pen. Use to move the turtle to specific coordinates without drawing. teleport(50, -20)
leap Retracts the pen, moves forward the given distance, and then extends the pen. Use to move the turtle relative to its current position without drawing. leap(30) leap(-25)
hop Works like leap, but moves sideways (positive to the left or negative to the right) without changing the turtle's orientation. Like leap, it does not draw while moving. hop(15) hop(-5)
Drawing Shapes:
Function Effect Example(s)
drawCircle Draws a "circle" made out of many small lines just like the regular circle function, but centers it on the current turtle position, and puts the turtle back where it started when it's done. The argument specifies the radius of the circle. drawCircle(50)
drawEllipse Draws an ellipse centered on the current turtle position, with the given radius and aspect ratio (i.e., ratio between the two radii of the ellipse). The given radius extends to the left and right of the given turtle position, while the other radius extends in front of and behind the turtle. As with drawCircle, the turtle ends up where it started. drawEllipse(100, 0.5) drawEllipse(50, 2)
drawDot Draws a filled circle centered at the current turtle position, using the pen color as the fill color and without any border. The result is faster and more smoothly circular than drawCircle, but cannot have separate pen and fill colors. drawDot(15)
drawSquare Draws a square centered at the current turtle position, and puts the turtle back where it started. The argument determines the length of each side of the square. drawSquare(50)
drawRectangle Draws a rectangle centered at the current turtle position, and puts the turtle back where it started. The arguments determine the rectangle's length (to the front and back of the turtle) and width (to the left and right of the turtle) respectively. drawRectangle(50, 100)
drawPolygon Draws a regular polygon centered at the current turtle position, and puts the turtle back where it started. The arguments specify the length of each side and the number of sides, respectively. One side will always be parallel to the turtle's current position to its left. drawPolygon(60, 3) drawPolygon(30, 12)
Drawing Text:
Function Effect Example(s)
fontsize Sets the current font size. The default is 18. fontsize(32)
align Sets the current font alignment. Must be one of "left", "right", or "center". The default is "center". align("left")
drawText Draws text North of the current turtle position, without moving the turtle. Text cannot be rotated. drawText("Hello")
Function Effect Example(s)
setupTurtle Resets everything including the window title and background color and creates a new turtle window if necessary. setupTurtle()
noTrace / doTrace / showPicture Use noTrace to turn off animation completely, and doTrace to turn it back on. When animation is turned off, you must use showPicture to update the display (some things may not be drawn until showPicture is called). This can be even faster than speed 0 for complicated pictures.
Random Colors:
Function Effect Example(s)
randomPastelColor Returns a random color name string from a fixed set of lighter pastel colors. color(randomPastelColor())
randomVibrantColor Returns a random color name string from a fixed set of bright highly-saturated colors of various hues. bright = randomVibrantColor()
randomMutedColor Returns a random color name string from a fixed set of muted colors with medium brightness and various hues. pencolor(randomMutedColor())
randomWarmColor Returns a random color name string from a fixed set of well-saturated colors with warm hues (pink, red, orange, yellow, brown, and some yellower greens). warm = randomWarmColor()
randomCoolColor Returns a random color name string from a fixed set of well-saturated colors with cool hues (purple, blue, turquoise, and darker/bluer greens). fillcolor(randomCoolColor())