---
title: Shopware Installation on Windows | Shopware Community Hub
description: >-
  Learn how to install Shopware on Windows 11 with WSL2, Ubuntu, Docker, and the
  Docker-based Shopware setup.
canonical_url: 'https://hub.shopware.com/learn/unit/shopware-installation-on-windows'
---

# Shopware Installation on Windows

<LearningObjectives>

- Set up WSL2 and Ubuntu as the Linux layer for local Shopware development on Windows.
- Explain how the Windows, WSL2, Docker, and Shopware layers fit together.
- Install Docker inside Ubuntu and verify that the setup works.
- Create and install a Shopware project with the Docker-based setup.
- Troubleshoot common setup problems on Windows and WSL2.

</LearningObjectives>

# Shopware Installation on Windows

<YoutubeEmbed link="https://www.youtube.com/watch?v=Dq8hvEUdeMU" />

This learning unit shows a Windows setup path for Shopware based on **WSL2**, **Ubuntu**, and **Docker**.

If you install Shopware directly on Windows without a Linux layer, the setup quickly becomes harder to maintain. WSL2 gives you a Linux environment inside Windows, and Docker then runs the Shopware stack inside that Linux environment.

By the end of this learning unit, you will have a functional Shopware installation running locally on Windows.

## Understand the Setup Layers

Before you begin the installation steps, it helps to separate the setup into layers:

- **Windows**
- on top of Windows: **WSL2**
- inside WSL2: **Ubuntu**
- inside Ubuntu: **Docker**
- inside Docker: **Shopware**

That way, Windows stays your host system, while the Shopware development stack runs in Ubuntu where the tooling is easier to manage.

## What You Need for This Setup

- A system running **Windows 11**.
- A browser (Edge, Chrome, Firefox, etc.)

Keep this separation in mind throughout the setup:

- **Windows side**: VS Code, browser, PowerShell, terminal app.
- **Ubuntu side (inside WSL2)**: `apt`, Git, Docker, Shopware project files, and Shopware commands.

In the next steps, you first install WSL2 and Ubuntu. After that, you prepare the Ubuntu environment with the tools needed for Shopware development.

## Setting Up WSL2 (Windows Subsystem for Linux)

WSL2 is a lightweight Linux subsystem for Windows, providing a seamless environment to run Linux applications.

### Steps to Install WSL2

1. **Open PowerShell (Run as Administrator):**

   ```bash
   wsl --install
   ```

2. **Restart your computer** when prompted.

3. **Check whether a Linux distribution is already installed:**

   ```bash
   wsl --list
   ```

   If WSL2 is installed but no distribution exists yet, Windows may report that no distributions are installed.

4. **List available distributions:**

   ```bash
   wsl --list --online
   ```

   The exact list can change over time. For this setup, use **Ubuntu**.

5. **Install Ubuntu:**

   ```bash
   wsl --install Ubuntu
   ```

   This downloads and installs Ubuntu inside WSL2.

6. **Create your Ubuntu user:**

   - After installation, you will be prompted to create a username and password.
   - You can choose your own values. In demos, simple names such as `shopware` are often used.

7. **Understand where you are running commands:**

   After Ubuntu opens, your prompt changes because you are no longer in PowerShell. You are now inside the Ubuntu shell.

   - Use `exit` if you want to leave Ubuntu and return to Windows.
   - In Windows Terminal, you can later open Ubuntu directly from the profile dropdown.

8. **Verify that you are really inside Ubuntu:**

   ```bash
   uname -a
   ```

   This command works as a Linux verification step. It is a simple way to confirm that you are running inside Ubuntu rather than in a Windows shell.

9. **Update and upgrade packages:**

   ```bash
   sudo apt update && sudo apt upgrade
   ```

   This refreshes package information and installs available updates.

   If you encounter a time synchronization issue, correct the system clock first and then rerun the command.

## Install the Essential Ubuntu Tools

The next step is to prepare the Ubuntu environment you will actually use for Shopware development.

### Install zsh and Git

Run:

```bash
sudo apt install zsh
```

```bash
sudo apt install git
```

### Install Oh My Zsh

To make the terminal experience more comfortable, also install [Oh My Zsh](https://ohmyz.sh/).

Oh My Zsh is a configuration framework for the Z shell. It gives you a cleaner prompt and useful shell defaults, which makes everyday terminal work easier once you start using Ubuntu more often.

Only run commands like this when you trust the source:

```bash
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
```

When asked whether you want to switch the default shell to `zsh`, confirm with `y`.

Then restart the Ubuntu terminal.

## Install Docker in Ubuntu

At this point, Windows is still your host system, but Docker for this setup runs inside **Ubuntu under WSL2**.

Use the [official Docker installation](https://docs.docker.com/engine/install/ubuntu#install-using-the-repository) steps for Ubuntu.

### Add Docker's Repository

Run the following commands of the official docker documentation in Ubuntu:

```bash
sudo apt update
```

```bash
sudo apt install ca-certificates curl
```

```bash
sudo install -m 0755 -d /etc/apt/keyrings
```

```bash
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
```

```bash
sudo chmod a+r /etc/apt/keyrings/docker.asc
```

Then add Docker's package source:

```bash
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
```

After that, refresh the package list again:

```bash
sudo apt update
```

### Install Docker Packages

Now install Docker itself:

```bash
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

### Verify the Docker Installation

Check whether Docker is running:

```bash
sudo systemctl status docker
```

If Docker is not running, start it manually:

```bash
sudo systemctl start docker
```

Then verify the installation with:

```bash
sudo docker run hello-world
```

This confirms that Docker is installed and able to run containers inside Ubuntu.

## Create the Shopware Project

Once Docker works, the Shopware-specific part is almost the same as on macOS. The main difference is that you use Ubuntu tools such as `apt` instead of macOS tools such as Homebrew.

First, install `make`:

```bash
sudo apt install make
```

Then create a working directory, in this case it will be the path `~/Code/sw6` from the home directory:

```bash
mkdir Code
```

```bash
cd ~/Code
```

```bash
mkdir sw6
```

```bash
cd sw6
```

Now create the Shopware project with Docker:

```bash
docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup 6.7.9.1
```

If you prefer, you can also omit the version number and let the setup use its default version:

```bash
docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup
```

This setup creates the Shopware project for you and writes the generated files into your local folder. In the video, Elasticsearch is skipped here as well, so answer **No** at that prompt.

After project creation, you will see files such as:

- `compose.yaml` for Docker services.
- `compose.override.yaml` for local overrides.
- `composer.json` and `composer.lock` for the PHP dependencies.

## Start Containers and Install Shopware

Once the project exists, start the containers:

```bash
make up
```

You can inspect running containers with:

```bash
docker ps
```

Then install Shopware:

```bash
make setup
```

This is the same idea as in the macOS Docker setup: start the stack first, then run the installer inside it.

## Open the Project and Verify the Installation

Open the project in **VS Code on Windows**, not inside Ubuntu:

```bash
code .
```

Remember the setup model here:

- **Windows** is where your editor and browser live.
- **Ubuntu inside WSL2** is where your Shopware project, Docker, and Linux commands run.

After `make setup` finishes, open:

- Storefront: `http://localhost:8000`
- Administration: `http://localhost:8000/admin`

Use these default admin credentials:

- **Username:** `admin`
- **Password:** `shopware`

If the administration opens and the login works, the local installation is ready.

## First Development Commands

To verify that you can run Shopware commands inside the running Docker setup, clear the cache:

```bash
docker compose exec web bin/console cache:clear
```

That confirms that the container setup is working and that you can execute Shopware commands in it.

## Troubleshooting and Tips

### Common Issues

- **Time sync issues:** Adjust the system clock if Linux time differs from real time.
- **Long paths on Windows:** Keep the project inside WSL/Ubuntu to avoid Windows path issues.
- **Docker commands fail with permission errors:** Use `sudo` or configure Docker for non-root usage later.
- **Docker is not running:** Check `sudo systemctl status docker` and start it with `sudo systemctl start docker`.
- **Local web server is not reachable:** Make sure ports such as `8000`, `3306`, and `6379` are not already in use.
- **Unknown database or empty database:** Rerun `make setup`.

### Tips

- Use Git for version control from the start.
- Keep Windows tools on Windows and Ubuntu tooling in Ubuntu.
- If you switch back to PowerShell by accident, reopen the Ubuntu terminal profile or run `wsl`.

<CollapsibleGroup>

<CollapsibleSection title="Legacy Alternative: DevEnv with Nix (Deprecated)">

This section is kept only as a legacy fallback. For new Windows setups in this learning unit, use the **WSL2 + Docker** path above.

The older DevEnv path looked like this:

1. Install **Nix**:

   ```bash
   curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
   ```

2. Install **Cachix** and activate the caches:

   ```bash
   echo "trusted-users = root ${USER}" | sudo tee -a /etc/nix/nix.conf && sudo pkill nix-daemon
   nix-env -iA cachix -f https://cachix.org/api/v1/install
   cachix use devenv
   cachix use shopware
   ```

3. Install **DevEnv**:

   ```bash
   nix-env -iA devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable
   ```

4. Create a Shopware project with Composer:

   ```bash
   nix-shell -p php83 php83Packages.composer
   mkdir ~/code && cd ~/code
   composer create-project shopware/production shopware6
   cd shopware6
   ```

5. Start the environment and install Shopware:

   ```bash
   devenv up
   devenv shell
   bin/console system:install --basic-setup --create-database --force
   ```

</CollapsibleSection>

</CollapsibleGroup>

## Summary

In this learning unit, you learned:

- How the Windows, WSL2, Ubuntu, Docker, and Shopware layers fit together.
- How to install WSL2, Ubuntu, and the basic development tools.
- How to install Docker inside Ubuntu and verify that it works.
- How to create and install a Shopware project with the Docker-based setup on Windows.

With this setup in place, you are ready to continue with local Shopware development on Windows.
f