---
title: Shopware Installation on macOS | Shopware Community Hub
description: >-
  Learn how to install Shopware on macOS with Docker by preparing the required
  tools, creating a project, running the setup, and verifying the local shop.
canonical_url: 'https://hub.shopware.com/learn/unit/shopware-installation-on-macos'
---

# Shopware Installation on macOS

<LearningObjectives>

- Prepare the required tools for a local Shopware setup on macOS.
- Explain why Docker simplifies a first Shopware installation.
- Create and install a Shopware project with the Docker-based setup.
- Verify that the storefront and administration are working locally.

</LearningObjectives>

# Shopware Installation on macOS

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

This learning unit shows a clean macOS setup path for Shopware with Docker.

If you install Shopware completely by hand, you need several parts at once: PHP, a database, a web server, Node.js, and the right PHP extensions. For beginners, that setup is easy to break and hard to debug.

This is where Docker helps. Docker packages the required services into a ready-to-run environment, so you can focus on getting Shopware running first.

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

## What You Need for This Setup

Before you start, make sure these tools are available on your Mac:

- **Google Chrome**
- **iTerm2**
- **Visual Studio Code**
- **Docker on macOS**, for example, through **OrbStack**

This learning unit uses Docker as the standard setup path.

## Install the Essential Tools

You will use **Visual Studio Code** as your editor and **iTerm2** as your terminal.

### Installing iTerm2

1. Open the [iTerm2 downloads page](https://iterm2.com/downloads.html).
2. Download the latest stable release.
3. Extract the `.zip` file.
4. Move the application into your `Applications` folder.
5. Start iTerm2 once to confirm it opens correctly.

![iterm2](./assets/shopwareInstall-iterm2.jpg)

### Installing VS Code

The process is similar:

1. Download [Visual Studio Code](https://code.visualstudio.com/download).
2. Install it like any other macOS application.
3. Start it once to confirm it works.

![vscode](./assets/shopwareInstall-vscode.jpg)

## Install Docker with OrbStack

For this macOS setup, the video uses [OrbStack](https://orbstack.dev/) as the Docker-compatible runtime.

OrbStack is a lightweight and user-friendly way to run Docker workloads on macOS. It is a good fit for local Shopware development and is free for personal use.

Install OrbStack first, then open a terminal, and run the default verification container:

```shell
docker run -it -p 80:80 docker/getting-started
```

This container is **not related to Shopware**. Its only purpose is to confirm that your Docker setup works before you continue with the Shopware installation.

If the command runs successfully, Docker is ready. Stop the container again with `Ctrl + C` before moving on.

## Prepare the Shopware Docker Setup

Before proceeding, confirm that **Homebrew** is available on your system.

<Callout title="Hint" type="warning">

Homebrew is used here for macOS, but Linux users (or Windows with WSL2) can use their package manager (for example apt).

</Callout>

```shell
brew --version
```

Homebrew is the package manager we rely on to install and manage development tools on macOS. Verifying that it is installed and up to date ensures we can seamlessly install required dependencies such as `make`.

Next, install `make` using Homebrew:

```shell
brew install make
```

You need `make` because the Shopware Docker setup provides a Makefile with the main commands for starting and installing the project.

## Creating a New Shopware Project

Start by creating a project directory:

```shell
mkdir my-project
```

And navigating into it:

```shell
cd my-project
```

Now, generate a fresh Shopware installation using Docker:

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

If you want to install a specific Shopware version, you can provide it explicitly:

```shell
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
```

This command runs a temporary Docker container that:

- Uses a preconfigured development image with PHP, Node.js, and Caddy.
- Creates a fresh Shopware project inside your current directory.
- Writes all generated files to your local folder.
- Automatically removes the container once setup is complete.

When prompted for **Elasticsearch**:

- Choose **No** for local testing or small datasets.
- Choose **Yes** if you plan to work with large catalogs or advanced search features.

For a first local installation, the default database-based search is enough.

### Starting the Environment

Once the project is created, start all required services by running:

```shell
make up
```

This launches all required containers in the background.

At this point, Shopware can be installed in **one of two ways**.

## Installing Shopware

Once the containers are running, the next step is to install Shopware itself. You can do this either through the browser or directly in the terminal.

### Option 1: Installing via CLI (Recommended)

For a fast, non-interactive setup, run:

```shell
make setup
```

### Option 2: Installing via Browser

Open the following URL in your browser:

```shell
http://localhost:8000
```

Follow the on-screen installation wizard to complete the setup.

Both methods install Shopware and prepare your local development environment. We use the CLI installer here because it is the faster and more guided option for this setup.

### Verifying the Installation

Once the installation is complete, open your browser and visit:

```shell
http://localhost:8000
```

If the Shopware demo storefront loads successfully, your installation is complete.

## Managing the Environment

- Stop the containers:

  ```shell
  make down
  ```

- Start them again:

  ```shell
  make up
  ```

- Remove containers and all data:

  ```shell
  docker compose down -v
  ```

## Development Workflow

You can run Shopware commands directly from your machine without manually entering a container. For example, to clear the Shopware cache:

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

The provided **Makefile** also includes helpful shortcuts for frontend development:

- `make build-administration`: Rebuild the admin interface once.
- `make build-storefront`: Rebuild the storefront once.
- `make watch-admin`: Watch and rebuild admin assets automatically.
- `make watch-storefront`: Watch and rebuild storefront assets automatically.

Keep in mind that once you have finished with development of the storefront or administration, you need to run the `make build-administration` or `make build-storefront` command to rebuild the assets.

<Callout title="Useful for Developing" type="info">

The watch commands are especially useful during development because you do not need to trigger a manual rebuild after every JavaScript change.

You will see more about it in our [Shopware Frontend Development Essentials](/learn/path/shopware-frontend-development-essentials) learning path.

</Callout>

## Accessing the Admin Panel

To verify admin access, open:

```shell
http://localhost:8000/admin
```

Log in using the default credentials:

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

You should now be logged in successfully and ready to continue.

## Final Local Check

To complete the local setup, review the storefront domain configuration:

1. Add or review the domain:

    - Navigate to the storefront configuration.

    - Switch to HTTP and use localhost:8000.

    - Set the language, currency, and localization as needed.

    - Save the configuration and refresh the storefront to see the changes.

![demostore](./assets/shopwareInstall-demoStore.jpg)

Now the shop is set up locally on your machine and ready for the next development steps.

## Extending Shopware

For further customization via plugins, apps, or themes, open the Shopware file system in VS Code and refer to our [documentation](https://developer.shopware.com/docs/guides/plugins/).

## Summary

In this learning unit, you learned:

- Which tools you need before starting a Shopware installation on macOS.
- Why Docker simplifies the setup of PHP, the database, the web server, and other required services.
- How to create a Shopware project with the Docker-based setup.
- How to install Shopware locally, verify the storefront and administration, and use the first development commands.

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