{{:martyv2:programming:python:rpi-logo-reg-screen.png?nolink&50|}}

===== 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.

<note>
**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 [[martyv2:userguides:raspberry_pi:primer|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.
</note>

===== 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:

<code bash>
python3 --version
</code>

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.

<code bash>
sudo apt update
sudo apt install python3 python3-venv python3-pip nano
python3 -m venv ~/marty-env
</code>

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 [[https://www.raspberrypi.com/documentation/computers/os.html#python|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:

<code bash>
~/marty-env/bin/python -m pip install martypy
~/marty-env/bin/python -c "from martypy import Marty; print('MartyPy import OK')"
</code>

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:

<code bash>
~/marty-env/bin/python -m pip show martypy
</code>

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.

<code bash>
~/marty-env/bin/python -m pip install --upgrade martypy
</code>

===== 4. Write and run a program =====

For a Pi mounted in Marty and connected by the expansion cable, return to the [[martyv2:userguides:raspberry_pi:start#raspberry_pi_configuration|serial configuration instructions]], then complete [[martyv2:userguides:raspberry_pi:start#check_that_it_worked|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:

<code bash>
~/marty-env/bin/python ~/marty_test.py
</code>

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:

<code bash>
source ~/marty-env/bin/activate
python ~/marty_test.py
</code>

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:

<code bash>
sudo apt install thonny
</code>

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:

<code bash>
~/marty-env/bin/python -c "import sys; print(sys.executable)"
</code>

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 [[https://www.raspberrypi.com/documentation/computers/os.html#use-the-thonny-editor|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 [[martyv2:userguides:raspberry_pi:start#troubleshooting|Marty Pi troubleshooting guide]]. |

===== Next steps =====

For expansion-cable control, continue with [[martyv2:userguides:raspberry_pi:start#check_that_it_worked|your first Marty program]]. For programming ideas, see [[martyv2:userguides:python:first_steps_with_python|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.//