Windows Subsystem for Linux Setup

Windows Subsystem for Linux (WSL) is a new 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. The filesystem access is slower than on regular Linux, so builds will take somewhat longer, but it's quite usable.

Install WSL

To install WSL, you need to be running a recent version of 64-bit Windows 10. Go to Control Panel > Programs >Windows Features, and check the box for Windows Subsystem for Linux.

After that, you'll have to reboot Windows. After it's rebooted, go to the Microsoft Store, search for Ubuntu, and install it.

Then launch Ubuntu. You'll see a terminal console window and you'll be asked some initial setup questions.

Install Build Tools

This step is the same as for regular 18.04 Ubuntu, so refer to that page, and then come back here.

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:

Download: file
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.

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.

Download: file
# 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.
This guide was first published on Apr 26, 2018. It was last updated on Apr 26, 2018. This page (Windows Subsystem for Linux Setup) was last updated on Jan 19, 2020.