Windows FAQ

postmarketOS is about creating a Linux-based OS for mobile devices, and so most of the developers use Linux for development as well. This is highly recommended, more people will be able to help you and it just makes more sense ideologically to use a free software based development environment for this. So if you are on Windows, consider setting up a Linux installation somewhere and use that for postmarketOS hacking, maybe on a spare laptop or Raspberry Pi or similar. Or run a VM inside of Windows if your really need to stick to that operating system. Running pmbootstrap on Windows is not supported.

With that being said, some people do try to run pmbootstrap with WSL etc, so this page exists. Let's keep all Windows related information in this wiki page and link to it where appropriate, instead of filling other wiki pages with Windows-specific information.

USB networking

NCM

As per MR pmaports!3670 the postmarketOS initramfs uses NCM instead of RNDIS for the USB networking gadget. This should work out of the box on Windows 11 but doesn't on Windows 10.

In case you want to access your device from Windows 10 you can set deviceinfo_usb_network_function="rndis.usb0" in /etc/deviceinfo.

For a new installation you can use steps like the following

$ pmbootstrap install
$ pmboostrap chroot -r
$ vi /etc/deviceinfo # add deviceinfo_usb_network_function="rndis.usb0"
exit, exit chroot

For Android device do:
$ pmbootstrap mkinitfs
$ pmbootstrap flasher flash_kernel

Or for non-Android do:
$ pmbootstrap install
Flash again, or copy ~/.local/var/pmbootstrap/chroot/rootfs_*/boot/* /run/media/$USER/pmOS_boot/

Then the device should use RNDIS for USB networking again.

RNDIS

Normally Windows should already have / should be able to assign the right drivers. If it's not the case and before going further first check if you can assign Microsoft RNDIS USB driver to the device. If no RNDIS driver is showing up, follow what's next.

If your device is listed as an ADB device you'll have to uninstall it (with the driver) first.

if you can't find the RNDIS driver you'll have to create an inf file that match your computer OS version.

Take the file in the guide from microsoft.

Once you have the file, go into device manager. Follow the dialogs up to the 'choose a driver', point it to your .inf , accept the security warnings and you're done, using a ssh client you should be able to login.

Can I use pmbootstrap in WSL?

Yes, see Connecting USB devices to WSL for further details.

1. Install the latest release of usbipd.

2. Run PowerShell or Command Prompt as admin.

3. Run usbipd wsl list, locate your device and its BUSID.

4. Run usbipd attach --busid BUSID (replacing BUSID with your device's BUSID, 2-1 for example).

You should now have access to your device from within WSL. Run lsusb from within WSL to confirm that it has connected.

If your device gets detected as ADB Interface/Recovery

1. Click Update Driver - choose "Composite USB Device"("Составное USB Устройство" in Russian locale of Windows)

2. Unknown device with name RNDIS device would appear

Installing RNDIS

1. Click Update Driver - choose "Browse my computer for driver software." and then "Let me pick from a list of device drivers on my computer."

2. Choose "Network Adapter" section

3. Choose "Microsoft" manufacturer

4. Choose "Remote NDIS compatible device"

On Windows 10 version 1709, the device is "Remote NDIS based Internet Sharing Device"

5. That's all! Wait for Windows to install driver for your device and SSH into it!

Using PuTTY instead of the Terminal inside the VM

If your phone only connects successfully to the VM, but you want to use PuTTY (or another Windows SSH client) for Telnet/SSH:

• Start a SSH server in the VM
• Connect via PuTTY to the VM
• Then connect to the device from that SSH session

Loopback partitions

By default, your kernel probably boots up with loop.max_part=0, which prevents pmbootstrap install --fde from generating an image. When this happens, you'll see an error message about /dev/loop0p1 not existing, possibly also some error messages about being unable to inform the kernel about new partitions. To fix this, you'll need to add the following to your [wsl2] section in %HomeDrive%%HomePath%\.wslconfig:

kernelCommandLine="loop.max_part=32"

Flashing images to SD cards

It should be possible to write images with the usual command-line tools once you have WSL up and running. Alternatively, use Fedora MediaWriter.

Configuring USB Internet with a Windows host

Moved from the USB Internet article:

Configure the IP addresses like the screenshot above.