Problems setting up MARLIN¶
Nothing has run yet: you are still installing MARLIN, or still getting the Controller and robot brain connected.
Work through Install MARLIN and Run your program first. This page covers what goes wrong along the way.
python is not recognized as a command¶
Typical messages:
On Windows this almost always means the Add Python to PATH checkbox was left unticked when Python was installed. Re-run the Python installer, choose Modify, and make sure that option is on. You can also reinstall and tick it on the first screen.
Windows also ships a stub that opens the Microsoft Store instead of running
anything, usually when you type python3. Use python or py -3 instead.
On macOS and Linux, use python3.
The MARLIN icon is not in the activity bar¶
You have installed something, but no marlin silhouette appears down the far left edge of VS Code.
The usual cause is installing the wrong extension. Searching MARLIN also
returns Auto Build Marlin, an unrelated 3D-printer extension with far more
installs, and it is usually the first result. The one you want is MARLIN
Controller by PolyMate Pte Ltd. See
Install the VS Code extension
for the screenshot.
If the right extension is installed, reload VS Code. The icon appears near the bottom of the activity bar.
The extension refuses to run your program because of the Python version¶
The extension requires Python 3.10 or newer and will refuse to run rather than fail halfway, with a message in the MARLIN Console naming the version it found.
Check which interpreter is selected, then point the extension at a newer one: Select the Python executable in VS Code.
Python cannot import marlin¶
Typical message:
or an extension message saying the MARLIN API is not installed.
You do not install the MARLIN package yourself. The extension bundles it and adds it to the Python it launches. This message means the extension is using a different Python than the one that has it.
Check from a terminal inside VS Code (Terminal → New Terminal):
On macOS and Linux use python3. On Windows, python3 often opens the
Microsoft Store instead of running anything. Use python or py -3.
If this works in your terminal but not in VS Code, set Marlin-controller: Python Path to the Python executable from that terminal:
The import check fails in a terminal outside VS Code¶
This is expected, not a fault. The extension adds the bundled API to
VS Code's integrated terminal, not to every terminal on your computer. A
separate Command Prompt, PowerShell, or Terminal window will report
No module named 'marlin' even on a perfectly good install.
Run the check from Terminal → New Terminal inside VS Code, as described in Check the Python install.
Do not pip install marlin¶
There is nothing to fetch with pip. Any package published under that name on PyPI is not the MARLIN API, and once installed it takes priority over the bundled one, so imports start succeeding while every attribute and method is wrong.
If you already ran it, undo it:
Then run the import check again.
Setting the Python path did not help¶
Two things go wrong here:
- The path points at a folder, not the program. The setting wants the
executable itself:
C:\Python312\python.exe, notC:\Python312. - There is no interpreter to follow. Leaving the setting blank is the recommended setup, but it only works when the VS Code Python extension is installed and has an interpreter selected. On a fresh VS Code neither may be true.
Both are covered in Select the Python executable in VS Code.
The extension is unreachable¶
Typical message:
Check that:
- the MARLIN extension is running
- the Controller is plugged in over USB
- the program was launched from the extension
- no other MARLIN Python client is already connected
The Python API does not connect directly to USB.
If everything above looks right, you probably started the program with VS Code's own play button. See I pressed run and got "extension not reachable".
The Controller does not appear in the port list¶
You clicked Refresh and your Controller is not in the dropdown.
Work through the checklist in Controller: the USB cable, Controller power, unplugging and reconnecting, another USB port, and any serial discovery errors in the MARLIN Console.
Note that the port you are looking for is the Controller, not the robot. The robot is reached over Bluetooth from the Controller, and never appears as a serial port of its own.
The Controller port is not remembered between sessions. On each restart the extension selects the first port it finds, so if you have other serial devices attached you may need to Refresh and pick the right one every time. See Settings that persist.
I do not know which port in the list is the Controller¶
The dropdown shows every serial port on the computer, and the one pre-selected
for you is usually not the Controller. COM on Windows, tty.usbmodem on
macOS, ttyACM on Linux. The full naming table, and how to identify the right
port by unplugging and refreshing, are in
Which port is the Controller?.
Connect appears to work but nothing responds¶
The extension says it opened the port, but the firmware stays unknown and the robot brain never pairs.
You have most likely connected to a port that is not the Controller. On macOS
/dev/tty.debug-console is always present and opens without complaint.
Disconnect, then pick the port using
Which port is the Controller?.
The robot brain does not appear in the Rescan list¶
To pair, the Controller must already be connected. It is the Controller, not
your laptop, that performs the Bluetooth pairing. Brain names start with M_.
If the brain still does not appear or will not connect, it is most likely still paired to someone else's Controller. Hold its pairing button for about four seconds, then click Connect again within thirty seconds.
Full pairing steps are in Robot Brain and Connect the robot brain.
Pool server errors keep appearing while testing at home¶
Messages about not being able to reach the pool server, repeating on their own, usually mean a server URL is left over from an earlier session. The extension remembers it between sessions.
If you are not using a pool server, clear the server URL. See Field Network.