Bridgetown on Windows
The easiest way to use Bridgetown on Windows is to install the Windows Subsystem for Linux. This provides a Linux development environment in which you can install Bash, Ruby, and other tools necessary to run Bridgetown in an optimized fashion.
Installing the Windows Subsystem for Linux #
You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11.
Open PowerShell and run:
wsl --install --distribution Ubuntu-24.04
You might need to restart your computer during this process. Once the setup finishes, you’ll be asked to create a username and password for your Ubuntu installation. After that, you can launch Ubuntu directly from the Start menu and log in with your new credentials.
If the Ubuntu terminal doesn’t open, try running the installation command again and make sure the WSL feature is enabled in your Control Panel.
Install dependencies on Ubuntu #
Launch WSL from the Start menu and update your package list:
sudo apt update
Next, install the required dependencies:
sudo apt install build-essential rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev
Installing the Mise version manager #
We’ll use Mise, a version manager, to install Ruby and Node. Mise makes it easy to update development tools or switch between different versions whenever you need.
curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
source ~/.bashrc
Install Ruby #
The following command installs the latest version of ruby-3.x (if any 3.x version is not already installed) and makes it the global default version:
mise use --global ruby@3
Once Ruby is installed, you can verify it works by running:
ruby --version
Install Node #
The following command installs the latest version of node-24.x and makes it the global default:
mise use --global node@24
Once Node is installed, you can also verify it works by running:
node --version
Install Bridgetown #
Now all that is left is to install Bridgetown!
gem install bridgetown -N
Create a new Bridgetown site at ./mysite, as well as run bundle install and
npm install automatically:
bridgetown new mysite
cd mysite
Now you should be able to build the site and run a live-reload server:
bin/bridgetown start
Try opening the site up in http://localhost:4000. See something? Awesome, you’re ready to roll! If not, try revisiting your installation and setup steps, and if all else fails, reach out to the Bridgetown community for support.
Important for WSL Users
For the best experience, always create your projects within the native Linux file system (e.g., ~/my-projects) rather than on the Windows mount (e.g., /mnt/c/).
Developing inside /mnt/c/ causes significant performance lag, permission errors, and breaks live-reloading. This issue impacts WSL Version 2 and is not exclusive to Bridgetown. You can learn more about it here.
Installing VS Code on Windows and the WSL extension enables separate environments: the editor interface runs on Windows, while code execution and plugins run on WSL. Learn more about this in the Developing in WSL topic.