Python Programming

A Complete Guide to

import turtle
From Scratch — Basics to Advanced Projects

Including: Setup in VS Code & PyCharm, Error Fixes, Drawing Projects

Prepared for: Andoh

University of Mines and Technology, Tarkwa

Chapter 1: What is import turtle?
The turtle module is a built-in Python library for drawing graphics. It works like a
virtual pen on a canvas — you control a small arrow (the 'turtle') by giving it
movement commands, and it draws lines as it moves.

It is named after the Logo programming language from the 1960s, which used a
physical turtle robot that drew on paper. Python's turtle module brings that same idea
to your screen.

import turtle

That one line is all you need to load the module. Python includes turtle by default —
no installation required.

1.1 What can you do with turtle?

• Draw shapes: squares, triangles, circles, stars, spirals
• Create patterns and fractals
• Build simple games and animations
• Visualise algorithms (sorting, recursion)
• Learn programming logic visually

1.2 How it works

The turtle lives on a coordinate grid. The centre of the screen is (0, 0). Moving right
increases X. Moving up increases Y. The turtle starts facing right (East) and moves
forward in whichever direction it is facing.

Direction Coordinates change Example

Right (East) X increases (0,0) → (100,0)
Left (West) X decreases (0,0) → (-100,0)
Up (North) Y increases (0,0) → (0,100)
Down (South) Y decreases (0,0) → (0,-100)
Chapter 2: Setting Up — VS Code and PyCharm
Turtle uses a graphical window (Tkinter). Some IDEs have issues displaying this.
Here is how to set it up correctly in both VS Code and PyCharm.

2.1 Does turtle need to be installed?

No. The turtle module comes built into Python's standard library. You do NOT need
to pip install anything. If you get a ModuleNotFoundError for turtle, it means Python
itself was not installed correctly.

✔ TIP: Always run turtle scripts from your terminal/command prompt, not from
Jupyter Notebook. Jupyter does not support turtle graphics.

2.2 Setting up in VS Code

Step 1 — Install Python
Download Python from [Link]. During installation on Windows, tick 'Add Python
to PATH'. Choose version 3.8 or higher.

Step 2 — Install the Python extension in VS Code

Open VS Code. Press Ctrl+Shift+X to open Extensions. Search for 'Python' by
Microsoft and install it.

Step 3 — Select your Python interpreter

Press Ctrl+Shift+P. Type 'Python: Select Interpreter'. Choose the Python version you
installed (e.g. Python 3.11.x).

Step 4 — Create your turtle file

Create a new file, for example: my_turtle.py. Write your code and save it.

Step 5 — Run from the terminal (IMPORTANT)

⚠ WARNING: Do NOT click the green Play button in VS Code for turtle
scripts. This can cause a blank window or crash.

Instead, open the integrated terminal (Ctrl+`) and type:

python my_turtle.py

On Mac/Linux you may need to type python3 instead:

python3 my_turtle.py

VS Code [Link] fix (optional)

If turtle windows still misbehave, open your [Link] in VS Code and add:
 {
"[Link]": true
}

2.3 Setting up in PyCharm

Step 1 — Create or open a project
Open PyCharm. Create a New Project or open an existing folder. Make sure a
Python interpreter is selected for the project (File > Settings > Project > Python
Interpreter).

Step 2 — Create your turtle file

Right-click the project folder, select New > Python File, and name it (e.g.
turtle_test.py).

Step 3 — Run the file

You can use either:
• Right-click the file and select Run 'turtle_test'
• Or open the Terminal tab at the bottom and type: python turtle_test.py

⚠ WARNING: On some Windows systems with PyCharm, the turtle window

may open behind other windows. Check the taskbar if you do not see it.

2.4 Common Errors and Fixes

Error Cause Fix

ModuleNotFoundError: No Python not installed Reinstall Python from [Link]. On
module named 'turtle' correctly or using wrong Mac, ensure you are using the system
Python Python or a correctly installed version.
_tkinter.TclError: no display Running on a headless Run on your local machine, not a
name and no $DISPLAY server (no screen) remote server. Turtle requires a
variable display.
Turtle window opens and Script finishes before you Add [Link]() or [Link]() at
immediately closes see anything the end of your script.
Blank white window — turtle Ran with Play button in Run from the terminal instead: python
does not draw VS Code [Link]
AttributeError: module 'turtle' Typo in function name Check spelling. E.g. [Link]() not
has no attribute 'xxx' [Link]()
[Link] error on re- Old turtle window still Close the turtle window fully before re-
run open running the script.
Slow drawing / laggy Screen updates after Add [Link](0) at top and
animation every command [Link]() when ready to show
Chapter 3: The Basics — Movement and Drawing
3.1 Your First Turtle Program
import turtle

[Link](100) # Move forward 100 pixels

[Link]() # Keep the window open

Run this from your terminal. A window appears with a line drawn to the right.
[Link]() tells Python to wait — without it, the window closes instantly.

3.2 Movement Commands

Command Shortcut What it does
[Link](n) [Link](n) Move forward n pixels
[Link](n) [Link](n) or Move backward n pixels
[Link](n)
[Link](angle) [Link](angle) Turn right by angle degrees
[Link](angle) [Link](angle) Turn left by angle degrees
[Link](x, y) [Link](x, y) Jump to coordinate (x, y)
[Link](x) Move to x coordinate only

[Link](y) Move to y coordinate only

[Link]() Return to (0,0) facing right

[Link](r) Draw circle of radius r

[Link](size, color) Draw a filled dot

3.3 Pen Control

Command What it does
[Link]() Lift the pen — move without drawing. Also: [Link]()
[Link]() Put the pen down — start drawing. Also: [Link]()
[Link](n) Set line thickness to n pixels
[Link]('red') Set the line colour
[Link]('blue') Set the fill colour
[Link]('red', 'blue') Set pen and fill colour at once
turtle.begin_fill() Start recording a shape for filling
turtle.end_fill() Fill the shape recorded since begin_fill()
3.4 Drawing a Square — Step by Step
import turtle

for i in range(4):
[Link](100)
[Link](90)

[Link]()

This loop runs 4 times. Each time it moves forward 100 pixels and turns right 90
degrees. Four sides of 100 pixels each = a square.

3.5 Drawing a Triangle

import turtle

for i in range(3):
[Link](150)
[Link](120)

[Link]()

A triangle has 3 sides. The exterior angle is 120 degrees (360 / 3 = 120).

3.6 Drawing a Circle

import turtle

[Link](80) # Circle with radius 80 pixels

[Link]()

A negative radius draws the circle clockwise (below the starting point). You can also
draw partial circles (arcs):
[Link](80, 180) # A semicircle (half circle)
[Link](80, 90) # A quarter circle
Chapter 4: Screen Control and Colours
4.1 Setting Up the Screen
import turtle

screen = [Link]()
[Link]('My Drawing')
[Link]('black')
[Link](width=800, height=600)

Command What it does

[Link]() Create a screen object for more control
[Link]('text') Set the window title bar text
[Link]('color') Set background colour
[Link](w, h) Set window width and height in pixels
[Link](w, h) Set the canvas size (scroll area)
[Link]() Clear all drawings
[Link]() Reset screen and turtle to defaults

4.2 Colours — Three Ways to Set Them

Method 1: Named colours (strings)
[Link]('red')
[Link]('blue')
[Link]('gold')
[Link]('purple')
[Link]('orange')

Python turtle accepts over 140 named colours (same as Tkinter/HTML colour
names). Examples: 'red', 'blue', 'green', 'yellow', 'orange', 'purple', 'pink', 'cyan',
'magenta', 'white', 'black', 'gold', 'silver', 'brown', 'lime', 'navy', 'teal'.

Method 2: Hex colour codes

[Link]('#FF0000') # Red
[Link]('#00FF00') # Green
[Link]('#0000FF') # Blue
[Link]('#FFD700') # Gold

Method 3: RGB tuples

[Link](255) # Must set this first!
[Link](255, 0, 0) # Red
[Link](0, 128, 255) # Sky blue
[Link](255, 215, 0) # Gold
 Note: You must call [Link](255) before using RGB tuples. Without
it, RGB values must be between 0 and 1 (which is confusing). Setting
colormode(255) makes it behave like normal RGB.

4.3 Drawing Filled Shapes with Colour

import turtle

[Link]('blue', 'yellow') # pen=blue, fill=yellow

turtle.begin_fill()
for i in range(4):
[Link](120)
[Link](90)
turtle.end_fill()

[Link]()

The begin_fill() and end_fill() pair fills the enclosed shape with the fill colour.
Chapter 5: Controlling the Turtle's Appearance
5.1 Turtle Shape
[Link]('turtle') # Classic turtle icon
[Link]('arrow') # Default arrow
[Link]('circle')
[Link]('square')
[Link]('triangle')
[Link]('classic')

5.2 Turtle Size and Speed

[Link](stretch_wid=2, stretch_len=2, outline=1)
# Makes the turtle icon 2x larger

[Link](0) # Fastest (0 = no animation)

[Link](1) # Slowest
[Link](5) # Medium
[Link](10) # Fast

Speed value Meaning

0 Fastest — no animation, draws instantly
1 Slowest
2-5 Slow to medium
6-9 Medium to fast
10 Fast
'slowest', 'slow', 'normal', 'fast', 'fastest' String equivalents

5.3 Hide/Show the Turtle

[Link]() # Makes the arrow invisible while drawing
[Link]() # Makes it visible again

✔ TIP: Use [Link]() and [Link](0) together for complex

drawings that would otherwise be very slow to watch render.

5.4 Turtle Heading and Position

print([Link]()) # e.g. (0.0, 0.0)
print([Link]()) # e.g. 0.0 (facing right)
print([Link]()) # x coordinate
print([Link]()) # y coordinate

[Link](90) # Face North (up)

[Link](0) # Face East (right)
[Link](180) # Face West (left)
[Link](270) # Face South (down)
Chapter 6: The Object-Oriented Approach
(Recommended)
Instead of using the module-level functions ([Link](), etc.), you can create a
Turtle object. This is cleaner, more flexible, and lets you have multiple turtles at
once.

6.1 Creating a Turtle Object

import turtle

t = [Link]() # Create a Turtle object called 't'

[Link]('turtle')
[Link]('green')
[Link](5)

[Link](100)
[Link](90)
[Link](100)

[Link]()

Now instead of [Link](), you write [Link](). All the same methods work —
just on the object.

6.2 Multiple Turtles

import turtle

t1 = [Link]()
t2 = [Link]()

[Link]('red')
[Link]('blue')

[Link](-100, 0)
[Link](100, 0)

[Link](50)
[Link](50)

[Link]()

Both turtles draw at the same time (well, alternately), each independently controlled.

6.3 Screen Object

import turtle

screen = [Link]()
[Link]('My Art')
[Link]('black')
[Link](900, 700)

t = [Link]()
[Link]('white')
[Link](200)

[Link]() # Same as [Link]()

Chapter 7: Writing Text on the Canvas
7.1 [Link]()
import turtle

[Link]('Hello, World!', font=('Arial', 24, 'normal'))

[Link]()

Parameter Type Options / Example

arg (text) string 'Hello, World!'
move bool True = turtle moves to end of text, False = stays
align string 'left', 'center', 'right'
font tuple ('Arial', 18, 'normal') or 'bold', 'italic', 'bold italic'

Full example: Centred heading

import turtle

[Link]()
[Link](0, 200)
[Link]('Python Turtle Graphics', align='center', font=('Arial',
28, 'bold'))
[Link](0, 0)
[Link]()

[Link]()
Chapter 8: Keyboard and Mouse Interaction
Turtle can respond to keyboard and mouse events, making interactive programs
possible.

8.1 Keyboard Events — [Link]()

import turtle

screen = [Link]()
t = [Link]()

def move_forward():
[Link](20)

def turn_left():
[Link](30)

def turn_right():
[Link](30)

[Link]() # Must call this first!

[Link](move_forward, 'Up') # Arrow key up
[Link](turn_left, 'Left')
[Link](turn_right, 'Right')

[Link]()

Note: [Link]() is required before onkey() works. Without it, keypresses

are ignored.

8.2 Mouse Events — [Link]()

import turtle

screen = [Link]()
t = [Link]()

def go_to_click(x, y):

[Link]()
[Link](x, y)
[Link]()
[Link](10, 'red')

[Link](go_to_click) # Click anywhere to place a dot

[Link]()

8.3 Turtle Click Events — [Link]()

t = [Link]()

def on_turtle_click(x, y):

 [Link]('red')
print('Turtle was clicked!')

[Link](on_turtle_click)
[Link]()
Chapter 9: Advanced Features
9.1 Speeding Up with tracer()
By default turtle redraws the screen after every command, which makes complex
drawings very slow. You can disable this with tracer(0) and only update when you
are ready.
import turtle

[Link](0) # Turn off screen updates

# ... all your drawing commands here ...

for i in range(360):
[Link](2)
[Link](1)

[Link]() # Show everything at once

[Link]()

✔ TIP: tracer(0) + update() is the single biggest performance improvement for

complex drawings. A spiral that takes 30 seconds renders in under 1 second.

9.2 Stamps and Clones

import turtle

t = [Link]()
[Link]('turtle')

# Stamp the turtle shape at the current position

[Link]()
[Link](60)
[Link]()
[Link](60)
[Link]()

[Link]()

stamp() leaves a copy of the turtle shape on the canvas without moving. Each stamp
returns a stamp ID you can use to clear it later with clearstamp(id).

9.3 Saving Your Drawing

Turtle can save your drawing as a PostScript file, which you can then convert to PDF
or PNG.
import turtle

# ... your drawing ...

canvas = [Link]().getcanvas()
[Link](file='my_drawing.ps')
[Link]()
The .ps file can be opened in any PostScript viewer or converted to PDF using a tool
like Ghostscript or an online converter.

9.4 Custom Turtle Shapes

import turtle

# Register a custom polygon shape

my_shape = ((0, 0), (10, 5), (20, 0), (10, -5)) # Diamond-like
turtle.register_shape('diamond', my_shape)

t = [Link]()
[Link]('diamond')
[Link](100)

[Link]()
Chapter 10: Drawing Projects
10.1 Project 1 — Colourful Star
import turtle

colours = ['red', 'orange', 'yellow', 'green', 'blue', 'purple']

[Link](0)
[Link]('black')

for i in range(36):
[Link](colours[i % len(colours)])
[Link](200)
[Link](170)

[Link]()
[Link]()

This draws a beautiful 36-pointed star using 200px lines and 170-degree turns. The
colour cycles through the list.

10.2 Project 2 — Spiral Square

import turtle

[Link](0)
[Link]('navy')
[Link]('cyan')

length = 5
for i in range(200):
[Link](length)
[Link](91) # Slightly more than 90 creates the spiral
length += 2

[Link]()
[Link]()

10.3 Project 3 — Rainbow Circles

import turtle
import colorsys

[Link](0)
[Link]('black')
[Link](0)
[Link](255)

for i in range(360):
r, g, b = [int(x * 255) for x in colorsys.hsv_to_rgb(i / 360, 1,
1)]
[Link](r, g, b)
[Link](100)
 [Link](1)

[Link]()
[Link]()
[Link]()

This uses the colorsys module to cycle through every hue in HSV colour space,
drawing a circle at each step, rotated 1 degree.

10.4 Project 4 — Recursive Tree (Fractal)

import turtle

def draw_tree(branch_len, t):

if branch_len > 5:
[Link](branch_len)
[Link](20)
draw_tree(branch_len - 15, t)
[Link](40)
draw_tree(branch_len - 15, t)
[Link](20)
[Link](branch_len)

t = [Link]()
[Link](0)
[Link](90) # Face upward
[Link]()
[Link](0, -250) # Start from the bottom
[Link]()

draw_tree(110, t)
[Link]()

This uses recursion to draw a tree fractal. Each branch splits into two smaller
branches until the branch length drops below 5.

10.5 Project 5 — Bouncing Ball (Simple Animation)

import turtle
import random

screen = [Link]()
[Link]('Bouncing Ball')
[Link]('black')
[Link](800, 600)
[Link](0)

ball = [Link]()
[Link]('circle')
[Link]('yellow')
[Link]()
[Link](0)

dx = 3 # x speed
dy = 3 # y speed
while True:
[Link]([Link]() + dx)
[Link]([Link]() + dy)

# Bounce off walls

if [Link]() > 390 or [Link]() < -390:
dx *= -1
if [Link]() > 290 or [Link]() < -290:
dy *= -1

[Link]()
Chapter 11: Complete Quick Reference
Movement
Command Description
[Link](n) / fd(n) Move forward n pixels
[Link](n) / bk(n) Move backward n pixels
[Link](a) / rt(a) Turn right a degrees
[Link](a) / lt(a) Turn left a degrees
[Link](x, y) Move to coordinates (x, y)
[Link](x) Move to x coordinate
[Link](y) Move to y coordinate
[Link]() Go to (0,0), face right
[Link](r, extent) Draw arc of radius r, extent degrees
[Link](size, color) Draw a dot

Pen
Command Description
[Link]() / pu() Lift pen — no drawing on move
[Link]() / pd() Put pen down — draw on move
[Link](n) Set line width to n pixels
[Link](c) Set line colour
[Link](c) Set fill colour
[Link](pc, fc) Set pen and fill colour
turtle.begin_fill() Start recording fill area
turtle.end_fill() Fill area since begin_fill
[Link]() Clear drawings of this turtle
[Link]() Reset this turtle to start

Turtle Appearance
Command Description
[Link]('name') Set turtle icon shape
[Link](w, l, o) Scale turtle icon
[Link](n) Set drawing speed (0=fastest, 1=slowest)
Command Description
[Link]() / ht() Hide the turtle icon
[Link]() / st() Show the turtle icon
[Link](angle) Point turtle in given direction
[Link]() Return current heading (degrees)
[Link]() Return current (x, y) position

Screen
Command Description
[Link]() Create screen object
[Link]('t') Set window title
[Link]('c') Set background colour
[Link](w, h) Set window dimensions
[Link](255) Enable RGB colour mode
[Link](0) Disable auto screen refresh
[Link]() Manually refresh the screen
[Link]() / mainloop() Keep window open and listening

Events
Command Description
[Link]() Enable keyboard listening — call first!
[Link](func, 'key') Call func when key is pressed
[Link](func) Call func(x, y) when screen is clicked
[Link](func) Call func when turtle is clicked
[Link](func, ms) Call func after ms milliseconds

Text and Misc

Command Description
[Link](text, align, font) Write text on canvas
[Link]() Leave a copy of turtle shape
[Link](id) Remove a specific stamp
[Link]() Remove all stamps
turtle.register_shape('name', poly) Register a custom shape
[Link]() Create a new independent Turtle object
Chapter 12: Common Mistakes and Final Tips
Mistake 1 — No [Link]() at the end
# WRONG — window closes immediately
[Link](100)

# CORRECT — window stays open

[Link](100)
[Link]()

Mistake 2 — Forgetting penup() before moving

# WRONG — draws a line when moving to start position
[Link](100, 100)

# CORRECT
[Link]()
[Link](100, 100)
[Link]()

Mistake 3 — Using radians for angle arguments

# WRONG — turtle uses degrees, not radians
[Link](3.14) # Turns only 3.14 degrees, not 180!

# CORRECT
[Link](180)

Mistake 4 — Forgetting [Link]() for key events

# WRONG — keypresses do nothing
[Link](move_forward, 'Up')

# CORRECT
[Link]()
[Link](move_forward, 'Up')

Mistake 5 — Not calling colormode(255) before RGB

# WRONG — error or wrong colour
[Link](255, 0, 0)

# CORRECT
[Link](255)
[Link](255, 0, 0)

Final Tips
• Always end with [Link]() or [Link]() to keep the window open.
• Use [Link](0) and [Link](0) with [Link]() for fast complex
drawings.
• Use the object-oriented style (t = [Link]()) for cleaner, more flexible
code.
• Run turtle scripts from the terminal, not with the IDE Play button if you see
issues.
• Use [Link]() to remove the arrow and make the final drawing look
cleaner.
• Experiment! Turtle is the best way to learn Python loops, functions, and
recursion visually.

— End of import turtle Guide —