Your prototype works, and a second person is ready to help. You send the code, they connect the board, and the first afternoon disappears into choosing a Python interpreter and finding a serial port. For a small hardware team, the development environment is part of the handover: it decides whether someone can make the next change without borrowing the original developer's laptop.
This is a practical problem, not an argument about editors. In a February 2024 MicroPython support discussion, a user could list a board but not open it, despite already being in the expected serial-access group; the follow-up found another service interfering. Seeing the device and being able to work with it were separate steps.
On Linux we set up two routes for MicroPython work: tools in a local Python environment, and a VS Code development container. Both got as far as sending commands to a board. Comparing them answers a more useful question than "which editor is best?": what has to travel with the project so the next person can continue it?
Keep the computer's Python separate from the board's MicroPython
Code runs in two places. The computer runs tools such as mpremote, which talks to the board over USB serial. The board runs MicroPython and your hardware program. Selecting a Python interpreter in VS Code configures the computer side; it does not install or change firmware on the board.
For the local route we created a named Conda environment and installed mpremote in it:
conda create -n micropython python=3.12
conda activate micropython
python -m pip install mpremote
That shows the workflow, not a locked package set. Our working interpreter was Python 3.12.12 in that environment. For a handover, save the versions that actually worked and the package sources used, rather than an installer link that says latest.
Creating the environment also raised a package-channel terms prompt. That is a decision for whoever uses that channel, not an error to hide in a script; note it in the setup instructions if the environment depends on it.
VS Code extensions add completion, upload commands and serial monitoring. They should not be the only way the project is explained. Give your collaborator a plain terminal command to try before they start troubleshooting an extension.
Establish one clear connection to the board
We checked the device entry with ls -l /dev/ttyACM0; it belonged to the dialout group, which is why our setup added the user to that group and started a fresh session.
Use the port that actually belongs to your board; /dev/ttyACM0 is an example, not a permanent identity. List ports, then select one explicitly:
mpremote connect list
mpremote connect /dev/ttyACM0 repl
Do not confuse connect list, which lists serial ports, with mpremote ls, which lists files on the connected board. Our own notes mixed these up at first. The mpremote reference documents them separately.
If the board appears but access fails, check permissions on that port and whether another terminal or serial monitor holds it. If Linux runs inside a virtual machine, confirm the USB device is attached to that guest; our setup ran under VMware, so that boundary mattered.
The final local test entered the REPL, the interactive prompt on the device, and sent Pin(25, Pin.OUT).value(1), which lit the board's LED. Use the LED pin appropriate to your board when you repeat it.
A container can carry the tools, but USB still needs a path
The second route used Docker and Microsoft's Dev Containers extension: a .devcontainer directory in the project, and VS Code reopening the folder inside the container so the tools run there. Microsoft's Dev Containers documentation explains how that configuration records the toolchain.
The leading dot in .devcontainer matters; Linux file managers hide such directories by default (Ctrl+H shows them). When sharing the workspace, include the configuration and any Dockerfile it references, not just main.py.
A container helps when collaborators need identical host tools. A local environment can be simpler for one developer working directly with USB hardware. Neither removes the need to identify the board, make its serial device available and specify its firmware.
Our container configuration came from a third party, and we did not have its full device-access settings documented. Inspect those settings and keep them with the project. Host permissions and device availability inside the container are separate checks. If you adopt Docker's usual group-based setup, the docker group grants root-level privileges and is not the same as the narrower serial-access group; Docker's post-install guide describes the difference.
Run the project without confusing development with deployment
For a single file, the editor offered a "Run file on remote device" action. For a project split across files, we used a command that works the same from any editor:
mpremote mount . run main.py
Our main.py imported a function from driver.py, and the terminal confirmed the local directory was mounted at /remote. The board read files from the computer for the duration of the session.
Mounting is convenient when you are changing several modules, because you avoid copying each edit to the board. It does not mean those files will be there when someone powers the prototype from a wall adapter. The mount documentation describes the host directory being accessed over serial. Keep a separate deployment procedure for files the device must keep.
Tool versions matter here. In September 2026 the MicroPython project announced that its v1.30 preview changes mpremote's default soft-reset behavior, with a prerelease package following in October. Under the new behavior, state can survive between commands, including an already imported module after you replace its file. The announcement and follow-up explain when to request a soft reset explicitly. Do not assume an older installation behaves like the preview.
For a collaborator, the symptom may just be "I changed the file and it still does the old thing." A good handover says how to run again from a known state, with commands checked against the pinned tool version, and when a reset will interrupt what the prototype is doing.
Finish the handover on a second computer
Our two setups established a development connection and sent code to a board. To make that a real handover, have another person follow the instructions on a fresh workspace with the actual board. Ask them to make one small visible change, then return the prototype to its intended standalone startup state.
| Include with the project | Why the next person needs it |
|---|---|
| Board model and exact firmware build | Host software alone does not reproduce the device runtime |
| Host tool versions and environment definition | Unpinned package names resolve differently later |
| Serial-port discovery and access notes | Device names and permissions change between computers |
| One working run command | Makes the action behind an editor button visible |
| Deployment and restart instructions | Separates a live host mount from files stored on the board |
| A small expected result | Gives a clear point at which the setup is known to work |
Choose the environment your team can recreate and maintain. The meaningful test is that another person can change the prototype and say which files and versions produced the result.