Setting Up Python on a Raspberry Pi
Install MartyPy on the Raspberry Pi that will run your program. Python 3 normally comes with Raspberry Pi OS. The steps below install the required tools and keep MartyPy in its own Python environment.
Chromebook users: you do not need Chromebook Linux or a local Python installation for this route. Open a terminal on the Pi using Raspberry Pi Connect or SSH. See the Raspberry Pi Primer for setup and school network requirements. All commands below run on the Pi, not in a Chromebook terminal or a Python prompt.
1. Open the Pi's terminal
Use Connect's Remote shell, an SSH session, or the Terminal application on the Pi desktop. If you see the Python prompt >>>, type exit() first to return to the system terminal.
Check Python:
python3 --version
You should see Python 3.x.x. Use the Python 3 supplied with your supported Raspberry Pi OS; do not install Python 2. The Pi needs internet access for the installation steps.
2. Install the tools and create an environment
Run each command separately and stop to check any error before continuing. Package installation may ask for your Pi password or confirmation.
sudo apt update
sudo apt install python3 python3-venv python3-pip nano
python3 -m venv ~/marty-env
The last command creates an environment in marty-env inside your Pi user's home directory. It normally produces no output when successful. Create it once for that user; do not recreate it at every lesson.
From Raspberry Pi OS Bookworm onwards, pip cannot normally install into the OS-managed Python environment. A virtual environment is the supported approach; see Raspberry Pi's Python documentation. Do not use sudo pip or bypass the protection with --break-system-packages.
3. Install and check MartyPy
Use the environment's Python explicitly so the library goes into the right place:
~/marty-env/bin/python -m pip install martypy
~/marty-env/bin/python -c "from martypy import Marty; print('MartyPy import OK')"
The second command should print MartyPy import OK. It checks the installation only; it does not connect to or move Marty.
To check the installed library version:
~/marty-env/bin/python -m pip show martypy
For a later update, run the following in the Pi's terminal. Teachers should check their lesson programs after updating before rolling the change out across a class.
~/marty-env/bin/python -m pip install --upgrade martypy
4. Write and run a program
For a Pi mounted in Marty and connected by the expansion cable, return to the serial configuration instructions, then complete the first walking program. The library installation alone does not configure the serial port.
To run the saved example, including after reconnecting at a later lesson:
~/marty-env/bin/python ~/marty_test.py
No environment activation is needed with this full path. Keep your Python files in your home or project folder, outside marty-env, so the environment can be replaced without losing your programs.
Optional: activate the environment
If you prefer shorter commands, activate it in each new terminal session:
source ~/marty-env/bin/activate
python ~/marty_test.py
The prompt should now include (marty-env). Run deactivate when finished. Activation applies only to that terminal session; it does not change another terminal or your editor's interpreter.
Optional: use Thonny on the Pi desktop
If your Pi has a desktop, you can use Thonny locally or through desktop sharing. If it is not installed, install it from the Pi terminal:
sudo apt install thonny
In Thonny, use the interpreter selector in the bottom-right corner and Configure interpreter to select the Python executable inside your environment. Its path is /home/YOUR_PI_USERNAME/marty-env/bin/python; replace YOUR_PI_USERNAME with your actual Pi username. Do not assume it is pi. You can print the exact path from the terminal:
~/marty-env/bin/python -c "import sys; print(sys.executable)"
Choose the local Python 3 interpreter on the Pi with that executable. Menu wording may vary. Verify from martypy import Marty in Thonny before running your program. See Raspberry Pi's Thonny instructions. OS Lite has no desktop; use a terminal editor such as nano instead.
Troubleshooting
| Message or symptom | Next step |
|---|---|
| externally-managed-environment | Use ~/marty-env/bin/python -m pip install martypy, not a system-wide pip command. |
| No module named martypy | Check the interpreter used to run the program. Use the full environment path above or configure Thonny to match. |
| No such file or directory for the environment | Check that you are logged in as the Pi user who created it. Complete step 2 if that user has no environment yet. |
| Installation cannot download packages | Ask IT to check internet, DNS and package-download access from the Pi. |
| Import works but connecting to Marty fails | Check the cable, UART configuration and serial permissions in the Marty Pi troubleshooting guide. |
Next steps
For expansion-cable control, continue with your first Marty program. For programming ideas, see First Steps With Python and keep the expansion connection from the Pi guide when adapting Wi-Fi examples.
Documentation reviewed: 29 September 2026. These steps use the virtual-environment workflow documented for Raspberry Pi OS Bookworm and later.