Text of docs.python.org › 3.16 › library › turtle.html as Styx crawled it on Oct 8, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

turtle — Turtle graphics — Python 3.16.0a0 documentation

Navigation index modules | next | previous | Python » 3.16.0a0 Documentation » The Python standard library » Graphical user interfaces with Tk » turtle — Turtle graphics | Theme | turtle — Turtle graphics ¶ Source code: Lib/turtle.py 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. Turtle graphics is an implementation of the drawing tools introduced in Logo in 1967. It was created as an educational tool, and its instant, visible feedback makes it an effective way for learners to encounter programming concepts. It is also a convenient way to produce simple graphical output without bringing in external libraries. This document includes four main sections: Tutorial teaches the basics of turtle drawing.

Reference describes the functions, methods and classes this module defines. How-to guides detail how to handle specific tasks. Explanation provides background on the object-oriented interface. Note Turtle graphics requires the tkinter optional module . The python.org installers for Windows and macOS include it, but some Linux distributions and other platforms may package it separately. If import turtle fails with an error mentioning _tkinter , look for documentation from your distributor (that is, whoever provided Python to you).

Check this in advance if you’re planning to use turtle graphics with a learner. Tutorial ¶ New users should start here. In this tutorial we’ll explore some of the basics of turtle drawing. Starting a turtle environment ¶ In a Python shell, import all the objects of the turtle module: from turtle import * If you run into a Standard library module '_tkinter' was not found error, you’ll have to install the Tk interface package on your system.

Basic drawing ¶ Send the turtle forward 100 steps: forward ( 100 ) You should see (most likely, in a new window on your display) a line drawn by the turtle, heading East. Change the direction of the turtle, so that it turns 120 degrees left (anti-clockwise): left ( 120 ) Let’s continue by drawing a triangle: forward ( 100 ) left ( 120 ) forward ( 100 ) Notice how the turtle, represented by an arrow, points in different directions as you steer it.

Experiment with those commands, and also with backward() and right() . Many commands also have shorter aliases, such as fd() for forward() . Pen control ¶ Try changing the color - for example, color('blue') - and width of the line - for example, width(3) - and then drawing again. You can also move the turtle around without drawing, by lifting up the pen: up() before moving. To start drawing again, use down() . The turtle’s position ¶ Send your turtle back to its starting-point (useful if it has disappeared off-screen): home () The home position is at the center of the turtle’s screen.

If you ever need to know them, get the turtle’s x-y coordinates with: pos () Home is at (0, 0) . And after a while, it will probably help to clear the window so we can start anew: clearscreen () Making algorithmic patterns ¶ Using loops, it’s possible to build up geometric patterns: for steps in range ( 100 ): for c in ( 'blue' , 'red' , 'green' ): color ( c ) forward ( steps ) right ( 30 ) - which of course, are limited only by the imagination!

Let’s draw the star shape at the top of this page. We want red lines, filled in with yellow: color ( 'red' ) fillcolor ( 'yellow' ) Just as up() and down() determine whether lines will be drawn, filling can be turned on and off: begin_fill () Next we’ll create a loop: start = pos () while True : forward ( 200 ) left ( 170 ) if distance ( start ) < 1 : break distance(start) < 1 is a good way to know when the turtle is back at its start position.

Finally, complete the filling: end_fill () (Note that filling only actually takes place when you give the end_fill() command.) Reference ¶ Turtle methods and functions ¶ Most of the examples in this section refer to a Turtle instance called turtle . Move and draw ¶ turtle. forward ( distance ) ¶ turtle. fd ( distance ) ¶ Parameters : distance – a number 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.

The turtle’s heading does not change. >>> 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 Turn the turtle right by the specified angle . The angle is measured in degrees by default; the unit can be changed with degrees() or radians() . How the heading is measured 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 Turn the turtle left by the specified angle .

The angle is measured in degrees by default; the unit can be changed with degrees() or radians() . How the heading is measured 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 Move the turtle to an absolute position.

If y is None , x must be a pair of coordinates or a Vec2D , for example as returned by pos() . If the pen is down, a line is drawn. The turtle’s heading does not change. >>> tp = turtle . pos () >>> tp (0.00,0.00) >>> turtle . goto ( 60 , 30 ) >>> turtle . pos () (60.00,30.00) >>> turtle . goto (( 20 , 80 )) >>> turtle . pos () (20.00,80.00) >>> turtle . goto ( tp ) >>> turtle . pos () (0.00,0.00) turtle. teleport ( x , y = None , * , fill_gap = False ) ¶ Parameters : x – a number or None y – a number or None fill_gap – a boolean Move turtle to an absolute position.

Unlike goto(x, y), a line will not be drawn. The turtle’s orientation does not change. If currently filling, the polygon(s) teleported from will be filled after leaving, and filling will begin again after teleporting. This can be disabled with fill_gap=True, which makes the imaginary line traveled during teleporting act as a fill barrier like in goto(x, y). >>> tp = turtle . pos () >>> tp (0.00,0.00) >>> turtle . teleport ( 60 ) >>> turtle . pos () (60.00,0.00) >>> turtle . teleport ( y = 10 ) >>> turtle . pos () (60.00,10.00) >>> turtle . teleport ( 20 , 30 ) >>> turtle . pos () (20.00,30.00) Added in version 3.12. turtle. setx ( x ) ¶ Parameters : x – a number Set the turtle’s x coordinate to x .

The y coordinate is unchanged. >>> turtle . position () (0.00,240.00) >>> turtle . setx ( 10 ) >>> turtle . position () (10.00,240.00) turtle. sety ( y ) ¶ Parameters : y – a number Set the turtle’s y coordinate to y . The x coordinate is 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 Set the turtle’s heading 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 the turtle to the origin, coordinates (0,0). The turtle’s heading

The rest of this page is on the live site.