Spin Pro is now is available for Laravel!

Install to Windows

Spin is able to run on any Windows machine that supports Windows Subsystem Linux v2 (WLS2). This is a feature developed by Microsoft that allows you to run a Linux distribution on your Windows machine. It is supported in updated versions of Windows 10 and Windows 11.

Prerequisites

Spin requires a working Windows installation with Docker installed. There are two popular methods to install Docker on Windows:

  1. Install docker-ce on Windows Subsystem Linux v2 (WSL2) [recommended]
  2. Install Docker Desktop on Windows with WSL2 backend

Docker Installation Options

Optional software

You may want to consider installing this software to improve your development experience (this is what we use).

  • Windows Terminal - This is a great terminal application that will give you tab support for your CLIs.

Install Windows Subsystem Linux v2 (WSL2)

Both options require installing WSL2. We can follow the principles discussed in the official WSL2 documentation and prepare our machine to run "Windows Subsystem Linux v2" (WSL2). We prefer Ubuntu as our distribution. So if you're happy with that recommendation, run this command in PowerShell as administrator to install WSL2.

Install and use Ubuntu as your Windows Subsystem Linux distro

wsl --install -d ubuntu

A restart may be required.

WSL Install Command

After a reboot, you may be prompted to create a username and password for your new Ubuntu installation. This is a separate user from your Windows user.

WSL Create Username and Password

Once configured, you can confirm is working by opening a new PowerShell window and running:

Enter the Ubuntu shell

wsl

⚠️ Always be aware of what shell you're in (Windows or Ubuntu). You can always tell by the prompt.

What a Windows shell looks like

You can tell you're in a Windows shell by the prompt when you see the PS prefix and the C:\ prefix. Windows Shell

What a Linux shell looks like

When you're in a Linux shell, you'll see the different colors and things like /mnt/c for your Windows drive. Linux Shell

To go back to your Windows shell, type exit and press enter.

⚠️ Always run spin from the Linux shell. You'll need to run wsl from a Windows prompt to enter the Linux shell, then you can run spin after you complete the installation.

Installing docker-ce within Linux allows you to run the open source versions of Docker without installing any proprietary software.

If this option interests you, run wsl to enter a Linux shell and then follow our instructions for installing Spin on Linux.

Install Docker Community Edition to Linux (WSL2) →

OPTION 2: Install Docker Desktop

If you prefer to install Docker Desktop with the WSL2 backend, you'll need to download Docker Desktop from Docker's website.

Installation

Double click the setup file to begin the installation.

Configuration

If prompted, leave the default options checked.

Docker Configuration

Another restart may be required.

After the installation completes, you may be prompted to reboot your machine. If so, go ahead and do that.

Docker Reboot

Accept the terms

Once your computer comes back online, click on the Docker Desktop icon. The application will initialize and be sure to accept the terms.

Accept Docker EULA

Configuring your Docker Account

You will be prompted to login to your Docker account. If you don't have one, you can create one for free. For most cases, you can use Docker without creating an account.

Docker Login

Verify Docker Desktop

Validate Docker is working (run this in Windows Terminal)

docker info

It should return version information.

Docker Info

Run a simple container to ensure Docker is working

docker run --rm hello-world

It should return something like this.

Docker Run Hello World!

Download and install spin into WSL2

⚠️ Be sure to run wsl to enter the Linux shell before running the following commands.

Run the installer with this simple command in your terminal

Install Spin (no root permissions required)

bash -c "$(curl -fsSL https://raw.githubusercontent.com/serversideup/spin/main/tools/install.sh)"

The above script will install spin at the user level in ~/.spin, using less than 300KB of storage.

Spin will prompt you if you want Spin to modify your PATH variable. If you press "Yes" follow the instructions on the screen. If you press "No" you will need to manually add Spin to your PATH.

Configuring your PATH variable manually

If you did not add spin to your PATH during the installation, you can manually add it to your PATH by adding this to your shell profile:

Run echo $0 in your terminal to figure out which shell you are using.

Add spin to your path

# Add this to `~/.zshrc` or `~/.bash_profile`
export PATH="$HOME/.spin/bin:$PATH"

In order to apply the changes to your current terminal session, you will need to run the source command.

Use the "source" command to apply your profile changes immediately

# If you're using ZSH
source ~/.zshrc

# If you're using Bash
source ~/.bash_profile

Validate it's working

You should be able to run this and get a result 🥳

Confirm spin is working correctly by getting the version

spin version