WSL2: real Linux inside Windows

Your Windows laptop, a Linux kitchen

Here is a fact that changes how you should think about your Windows machine: almost every Rails application in the world runs on Linux in production. When you deploy to a VPS, to Heroku, to Fly.io, or to a Kubernetes cluster, your code runs on a Linux machine: not Windows.

For years that meant Windows users faced a bad trade-off: dual-boot into Linux, run a heavyweight virtual machine, or fight native Windows quirks that no Rails guide anticipates. WSL2 (Windows Subsystem for Linux, version 2) ends that trade-off. It runs a real Linux kernel, inside a lightweight virtual machine, wired directly into Windows. You get a real apt, a real filesystem, a real bash (the same primitives your production server uses) while your browser, your files, and your Windows apps keep running where they already are.

WSL1 vs. WSL2: why the version matters

WSL1 shipped first and was clever but incomplete: it translated Linux system calls into Windows calls on the fly, with no real Linux kernel underneath. Native gem extensions and database internals that assume real kernel behavior could misbehave.

WSL2 is a different design:

+----------------------------------------------------------+
|                        WINDOWS 11                         |
|                                                            |
|  +-------------------+      +---------------------------+ |
|  | Windows Terminal  |      |  VS Code (Windows)         | |
|  | Explorer, browser |      |  + Remote-WSL extension    | |
|  +-------------------+      +--------------+--------------+ |
|                                            | bridge         |
|  +-----------------------------------------v--------------+ |
|  |     Lightweight VM (Hyper-V), boots in seconds          | |
|  |  +----------------------------------------------------+ | |
|  |  |              Real Linux Kernel                      | | |
|  |  |  +------------------------------------------------+ | | |
|  |  |  | Ubuntu userspace: apt, bash, rbenv, PostgreSQL, | | | |
|  |  |  | Ruby, Rails, Puma                                | | | |
|  |  |  +------------------------------------------------+ | | |
|  |  +----------------------------------------------------+ | |
|  +-----------------------------------------------------------+ |
+----------------------------------------------------------+

The inner box is a real Linux kernel: the same one that boots on a bare-metal Ubuntu server. apt behaves like apt. pg_ctl behaves like pg_ctl. Native gem extensions compile as they do in production.

The one rule that saves you hours: where your code lives

Windows and WSL2 can each see the other's files, but not at the same speed. Windows drives are mounted inside WSL2 at /mnt/c, /mnt/d, and so on, reached through a network-style filesystem protocol. The huge number of small file reads a bundle install or rails server performs makes Rails feel sluggish over that boundary, and file watching (which Rails' code reloader and the Tailwind watcher rely on) can silently miss changes.

The rule for this whole course: your Rails projects live inside the Linux filesystem, under a path like ~/code/, never under /mnt/c/Users/.... Ruby, PostgreSQL and your app all install and run on the Linux side. Windows becomes the display: Windows Terminal shows you the shell, VS Code's Remote-WSL extension shows you the editor, your browser shows you localhost:3000. The actual computation never leaves Linux.

What you are going to build

Check your Windows version

WSL2 requires Windows 10 version 2004 (build 19041) or later, or any edition of Windows 11. Open PowerShell and run:

winver

A small window reports your version and build number. If you are below build 19041, run Windows Update before continuing: everything else in this course depends on it.

How this course is organized

1. Install WSL2, Ubuntu, and build tools
2. Get comfortable with the shell and the Windows/Linux boundary
3. Install Ruby with rbenv
4. Install and run PostgreSQL inside WSL2
5. Bridge VS Code to WSL2 with the Remote-WSL extension
6. Create and run your first Rails app

Every command in this course was tested on Ubuntu 24.04 under WSL2 on Windows 11. Type them yourself instead of copying: your fingers learn faster than your eyes.

Why not a full VM or dual-boot?

You could install VirtualBox and a full Ubuntu VM, or dual-boot Windows and Linux side by side. WSL2 beats both for daily Rails work:

• Integration: your Windows clipboard, browser, and files are one explorer.exe . away from your Linux shell: no copy-paste between VM windows.
• Speed: a lightweight, purpose-built VM with dynamic memory beats a general-purpose VM booting a full desktop you'll never look at.
• One machine to maintain: no partitioning, no separate OS to patch and reboot into: Ubuntu starts and stops like an app.

Let's boot your Linux kitchen.