Raspberry Pi Scratch: Getting Started with Block Programming and GPIO

Raspberry Pi Scratch projects use the visual block-based editor to teach programming logic, create interactive animations and games, and control hardware through the Pi’s GPIO pins. Scratch 3 is the current version and runs in the Chromium browser on Raspberry Pi OS Desktop at scratch.mit.edu, or as an offline desktop app. Running sudo apt install scratch on Bookworm installs the outdated Scratch 1.4. Use the browser version instead. This guide covers accessing Scratch 3 on Bookworm, the core block categories with practical examples, GPIO control with the Simple Electronics extension, and four beginner projects. For the broader context of programming on Pi including Python and Node.js, see Programming on Raspberry Pi: Languages, Tools, and Starting Points.

Last tested: Raspberry Pi OS Bookworm Desktop 64-bit | May 2025 | Raspberry Pi 4 Model B (4GB) | Scratch 3 (browser, scratch.mit.edu), scratch-gpio 11.0

Getting Scratch 3 on Raspberry Pi

Raspberry Pi OS Bookworm Desktop includes Chromium browser. Open it and navigate to scratch.mit.edu to use Scratch 3 online. No installation required. Creating a free Scratch account lets you save projects to the cloud; you can also save projects locally as .sb3 files without an account using File > Save to your computer.

For offline use without internet access, install the Scratch Desktop app:

# Download Scratch Desktop for Linux ARM64 from:
# https://scratch.mit.edu/download
# Then install the downloaded .deb:
sudo apt install -y ./scratch-desktop-*.deb

Verify Scratch 3 is accessible by opening it and confirming the version in the top menu. If the Scratch menu shows version 1.x, you have the legacy APT-installed version. Remove it and use the browser or Desktop app:

sudo apt remove scratch scratch2

Expected result: Scratch 3 opens showing the stage (white canvas area on the right), the sprite list below it, the block palette on the left, and the scripting area in the centre. The default project includes a cat sprite on an empty stage. If the browser shows an error about WebGL, update Chromium: sudo apt update && sudo apt install chromium-browser.

Scratch 3 Blocks and Core Concepts on Raspberry Pi

Scratch organises its commands into colour-coded block categories. Each block snaps onto others like puzzle pieces to build scripts. Scripts run when triggered by an event, typically the green flag button at the top of the stage.

Category	Colour	What it does	Example block
Motion	Blue	Move and rotate sprites	Move 10 steps
Looks	Purple	Change appearance, say text	Say “Hello!” for 2 seconds
Sound	Pink	Play sounds and music	Play sound Meow until done
Events	Orange	Start scripts on triggers	When green flag clicked
Control	Orange	Loops, waits, conditionals	Repeat 10 / If…then
Sensing	Cyan	Detect collisions, mouse, keyboard	Touching Mouse-Pointer?
Operators	Green	Maths and string operations	Pick random 1 to 10
Variables	Orange	Store and update values	Set score to 0

A basic sprite movement script using keyboard input, the foundation of most games:

In the scripting area, drag out these blocks and snap them together:

• Events: When [right arrow] key pressed
• Motion: Move 10 steps

• Events: When [left arrow] key pressed
• Motion: Move -10 steps

Click the green flag and press the arrow keys. The cat sprite moves left and right. This two-block script demonstrates the event-driven model: nothing happens until a trigger fires, then the attached blocks execute in order from top to bottom.

Variables store game state. Create a variable called “score”: click Variables in the palette, click “Make a Variable,” name it “score.” Then build:

• Events: When green flag clicked
• Variables: Set score to 0
• Control: Forever
• Control (inside forever): If [Sensing: touching Mouse-Pointer?] then
• Variables (inside if): Change score by 1
• Control (inside if): Wait 0.5 seconds

Click the green flag and hover the mouse over the sprite. The score increments each time the sprite detects a touch. This pattern (loop, sense, respond) is the core of interactive Scratch programs.

Controlling GPIO with Raspberry Pi Scratch

Scratch 3 can control the Pi’s GPIO pins through the scratch-gpio package, which provides a helper server that bridges Scratch’s extension protocol to the Pi’s GPIO hardware. This only works on Raspberry Pi OS Desktop with Scratch 3 running in the browser or as the Desktop app.

Install the scratch-gpio helper:

sudo apt update && sudo apt install -y python3-pip python3-gpiozero
pip3 install --break-system-packages scratchgpio

Start the scratch-gpio server before opening Scratch. Run this in a terminal and leave it running:

scratchgpio5

Open Scratch 3 in Chromium at scratch.mit.edu. Click the Extensions button (puzzle piece icon, bottom-left of the block palette). Scroll to find “Raspberry Pi Simple Electronics” and click it. A new “Simple Electronics” block category appears in the palette with blocks for turning GPIO pins on/off and reading button states.

LED blink example. Connect an LED to GPIO17 with a 330-ohm resistor to GND (anode to GPIO17 through the resistor, cathode to GND). In the scripting area:

• Events: When green flag clicked
• Control: Forever
• Simple Electronics (inside forever): Turn LED on GPIO 17 on
• Control: Wait 1 seconds
• Simple Electronics: Turn LED on GPIO 17 off
• Control: Wait 1 seconds

Expected result: The LED connected to GPIO17 blinks at 1Hz after clicking the green flag. The scratchgpio terminal window shows connection messages when Scratch communicates with it. If the LED does not respond, confirm the scratchgpio server is running in the terminal, that the Simple Electronics extension loaded in Scratch, and that the LED is wired correctly (anode to GPIO17 through a 330-ohm resistor, cathode to GND). For full GPIO wiring guidance, see Raspberry Pi GPIO: Pin Reference, gpiozero Guide, and Protocol Overview.

Simple Projects to Build with Raspberry Pi Scratch

1. Sprite animation. Use the Costumes tab to give a sprite multiple appearances, then alternate between them on a timer. Combine Motion, Looks, and Control blocks: When green flag clicked > Forever > Next costume > Wait 0.1 seconds. This creates a walking animation and introduces the concept of frame-rate control via wait blocks.

2. Clicker game. Create a sprite that moves to a random position whenever clicked. Track a score variable. When the sprite is clicked: Change score by 1, then set X to (pick random -200 to 200), set Y to (pick random -150 to 150). Add a 30-second countdown timer using a variable decremented in a loop, and show a “Game Over” message when it reaches zero. This project covers events, variables, random numbers, and timing.

3. LED blink with speed control. Build on the GPIO example by adding a variable called “speed” that controls the blink rate. Create two sprites as on-screen buttons: clicking one increases the speed variable, clicking the other decreases it. Use the speed variable in the Wait blocks of the LED blink loop. This introduces variable-controlled behaviour and multiple sprite interaction.

4. Button-triggered sound. Wire a push button between GPIO4 and GND (gpiozero internal pull-up handles the resistor). In Scratch with the Simple Electronics extension: When button on GPIO 4 pressed > Play sound [Meow] until done. This is the simplest possible physical interaction. Pressing a button triggers a software event and demonstrates the GPIO sensing direction (reading an input).

For projects that require more capability than Scratch provides (file saving, network requests, more complex GPIO control, or multi-file programs), the transition to Python is natural. The same LED and button hardware used in Scratch GPIO projects works identically with gpiozero in Python. See Raspberry Pi LED Python: Control, Blink, and PWM Dimming Guide for the Python equivalent of the GPIO projects above.

FAQ

Does Raspberry Pi Scratch work on Bookworm?

Scratch 3 works on Bookworm Desktop by running in Chromium at scratch.mit.edu or as the downloaded Scratch Desktop offline app. The APT package scratch on Bookworm installs the outdated Scratch 1.4, which is incompatible with the current GPIO extension and should not be used. Scratch requires a desktop environment. It does not run on Raspberry Pi OS Lite.

Can Raspberry Pi Scratch control GPIO pins?

Yes, with the scratch-gpio helper package installed and the Simple Electronics extension loaded inside Scratch 3. The scratch-gpio server must be running in a terminal before opening Scratch. Once set up, the Simple Electronics blocks turn GPIO pins on and off and read button state. Only GPIO pins configured as digital I/O are supported. PWM, I2C, and SPI are not accessible from Scratch directly.

Is Scratch good for learning programming on Raspberry Pi?

Yes, for beginners and younger learners. Scratch removes syntax errors from the equation by replacing typed code with drag-and-drop blocks. It teaches the core concepts (event-driven programming, loops, conditionals, variables, and state) that transfer directly to Python and other languages. Scratch cannot do file I/O, network requests, or complex data structures. Most learners outgrow it within months and transition to Python, the natural next step on the Pi.

What is the difference between Scratch and Python on Raspberry Pi?

Scratch is visual and block-based with no syntax to type; Python is text-based with a full programming language syntax. Scratch runs in a browser sandbox; Python runs as a native process with access to the file system, network, and all GPIO libraries. Scratch is the better starting point for children and complete beginners. Python is the correct tool for any project that needs hardware control beyond simple LED/button, file operations, web requests, or automation. Most Pi projects in tutorials and guides use Python. For the full language comparison, see Programming on Raspberry Pi: Languages, Tools, and Starting Points.

How do I save Scratch projects on Raspberry Pi?

In the browser version at scratch.mit.edu: create a free Scratch account and click Save now to save to the cloud, or use File > Save to your computer to download a .sb3 file to the Pi’s local storage. In the Scratch Desktop offline app: File > Save to your computer saves a .sb3 file. To reopen a saved project, use File > Load from your computer and select the .sb3 file. Projects saved as .sb3 files open on any device running Scratch 3.

References:

• Scratch 3 online editor: scratch.mit.edu
• Scratch Desktop download: scratch.mit.edu/download
• scratch-gpio documentation: github.com/cymplecy/scratch_gpio
• Raspberry Pi Scratch resources: raspberrypi.com/documentation

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (4GB). Last tested OS: Raspberry Pi OS Bookworm Desktop 64-bit. Scratch 3 via scratch.mit.edu, scratch-gpio 11.0.