Windows Subsystem for Linux (WSL) is a feature of Windows 10 that lets you run Ubuntu and other versions of Linux right in Windows. It's real Ubuntu, without the Linux kernel, but with all the software packages that don't need a graphical interface. You can build CircuitPython in WSL easily. It's easier to install than a Linux virtual machine.

Install WSL

The installation procedures for WSL continue to evolve. Rather than provide information here which quickly becomes outdated, we ask that you refer to Microsoft's official instructions: Windows Subsystem for Linux Installation Guide for Windows 10. Enable WSL 2, which is better for our purposes than WSL 1 in several ways.

Note that your PC must have hardware virtualization support. Virtualization must also be enabled in the BIOS OR UEFI.

One WSL 2 is set up, you need to choose a Linux distribution to install, as described in the document above. Choose Ubuntu 22.04, or if not immediately available, install 20.04, and optionally upgrade to 22.04.

Finish Linux Install

Once WSL is set up, just proceed with the regular Linux Setup.

Build CircuitPython

From this point on, you can build CircuitPython just as it's built in regular Ubuntu, described in the Build CircuitPython section of this guide.

Moving Files to Windows

You can copy files to and from Windows through the /mnt/c. For instance, if you want to copy a CircuitPython build to the desktop, do:

cp build-circuitplayground_express/firmware.uf2 /mnt/c/Users/YourName/Desktop

Warning: Don't build in a shared folder (in /mnt/c). You'll probably have filename and line-ending problems.

You might be tempted to clone and build CircuitPython in a folder shared with the Windows filesystem (in /mnt/c somewhere). That can cause problems, especially if you use git commands on the Windows side in that folder. The CircuitPython build assumes case-sensitive filenames, but Windows usually ignores filename case differences. You may also have line-ending problems (CRLF vs.  LF). It's better to clone and build inside your home directory in WSL, and copy files over to a shared folder as needed. It is possible to drag and drop files between WSL and Windows.

Mounting a CircuitPython Board in WSL

You can mount your ...BOOT or CIRCUITPY drive in WSL. Create a mount point and then mount it. Note that you'll have to remount each time the drive goes away, such as when you restart the board or switch between the BOOT drive and CIRCUITPY. So it's probably more convenient to copy files to the board from Windows instead of WSL.

# You only need to do this once.

# Choose the appropriate drive letter.
sudo mkdir /mnt/d

# Now mount the drive.
sudo mount -t drvfs D: /mnt/d

# Now you can look at the contents, copy things, etc.
ls /mnt/d
cp firmware.bin /mnt/d
# etc.

Editing Files in WSL

You can use the usual Linux editors in WSL, such as vim and emacs. You may need to install them explicitly. Visual Studio Code (not Visual Studio) is also available: do a websearch to find the latest instructions. Visual Studio Code in Windows has a WSL extension.

This guide was first published on Apr 26, 2018. It was last updated on Jul 22, 2024.

This page (Windows Subsystem for Linux (WSL) Setup) was last updated on Jun 12, 2024.

Text editor powered by tinymce.