Skip to content



What is devenv?

Imagine devenv to function as a dependency manager for the services and packages that you need to run your application for local development or even in a CI/CD context.

Similar to other package managers, devenv lets you describe what your environment should look like and locks dependencies to a specific version to help you compose a reproducible setup.

Devenv not only lets you choose from and install different versions of binaries (e.g., PHP, Node, npm), but it also allows you to configure and run services (like MySQL, Redis, OpenSearch). The binaries and states of the services are stored on a per-project level.

The main difference to other tools like Docker or a VM is that it neither uses containerization nor virtualization techniques. Instead, the services run natively on your machine.



As devenv is built on top of Nix, first install Nix with the following command based on your OS:

Using Oh My ZSH?

You probably won't be able to use the commands below. Use the following steps to continue using oh my zsh:

  • Open /etc/zshrc and look for lines enclosed in # Nix and # End Nix like so (probably at the end of the file):
# Nix

# ... content ...

# End Nix
  • Copy the lines block enclosed in # Nix and # End Nix
  • Open ~/.zshrc and add the copied lines to the end of this file
  • Initiate the terminal with source ~/.zshrc or reboot your terminal for nix to work
  • Delete the lines between # Nix and # End Nix from /etc/zshrc

Credits: "nixos installation issue,'command not found: nix'", StackOverflow


Next, install Cachix to speed up the installation:

nix-env -iA cachix -f


If this is the first time using cachix, you need to add your account to the trusted users:

echo "trusted-users = root ${USER}" | sudo tee -a /etc/nix/nix.conf && sudo pkill nix-daemon

Before installing devenv, instruct Cachix to use the devenv cache:

cachix use devenv


Finally, install devenv:

nix-env -iA devenv -f

Before booting up your development environment, configure Cachix to use Shopware's cache:

cachix use shopware

You can find the whole installation guide for devenv in their official documentation:

Getting started -


Depending on whether you want to set up a fresh Shopware project or contribute to the Shopware core, you have to choose between the Symfony Flex template or the Shopware project.

Since the environment is described via a devenv.nix file committed to version control, you can now boot up the environment:

devenv up


Make sure that the ports for the services are not already in use, or else the command will fail.

Check your default web services with the following commands:

Change your .env file to the correct database settings:


Start a new terminal, navigate to the project directory and run the following command to launch a devenv shell. This shell includes all needed programs (php, composer, npm, node, etc.) to initialize Shopware:

devenv shell

In the devenv shell, run the following command to initialize Shopware:

bin/console system:install --basic-setup --create-database --force

Open http://localhost:8000/admin in your browser after the installation has finished. You should see the Shopware admin interface.

The default credentials are:

  • User: admin
  • Password: shopware


When using Windows and WSL2, you need to change the default sales channel domain to http://localhost:8000.

Important: Do use http, not https.


If you wish to switch between multiple development environments which use devenv seamlessly, we recommend installing direnv.

When you enter a project directory using devenv, direnv will automatically activate the environment for you. This means you can use the binaries without having to run devenv shell manually, though you still have to run devenv up to start all services.

First, install direnv:

Afterward, add the following hook to your shell:

After you change into a project directory using devenv for the first time, you need to allow direnv to load the environment:

direnv allow
Automatic Shell Activation -

Default services

Here is an overview of services Shopware provides by default and how you can access them:

Mailhog (SMTP)smtp://
Redis (TCP)tcp://


Caddy is a powerful, enterprise-ready, open-source web server with automatic HTTPS written in Go.


Adminer is a full-featured database management tool written in PHP.



MailHog is an email testing tool for developers.


Customize your setup

To customize the predefined services to match your needs, e.g., changing the virtual host, database name, or environment variables, you can create devenv.local.nix to override the service definitions. It also allows you to add and configure additional services you might require for your local development.


After changing devenv.local.nix, please reload your environment.

// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

  # Disable a service
  services.adminer.enable = false;
  # Use a custom virtual host
  services.caddy.virtualHosts."http://shopware.swag" = {
    extraConfig = ''
      root * public
      php_fastcgi unix/${config.languages.php.fpm.pools.web.socket}
  # Customize nodejs version
  languages.javascript = {
    package = pkgs.nodejs-18_x;

  # Override an environment variable
  env.APP_URL = "http://shopware.swag:YOUR_CADDY_PORT";

Refer to the official devenv documentation to get a complete list of all available services and their configuration possibilities:

devenv.nix Reference -

Enable Blackfire

// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

  services.blackfire.enable = true;
  services.blackfire.server-id = "<SERVER_ID>";
  services.blackfire.server-token = "<SERVER_TOKEN>";
  services.blackfire.client-id = "<CLIENT_ID>";
  services.blackfire.client-token = "<CLIENT_TOKEN>";

Enable XDebug

// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

  # XDebug
  languages.php.extensions = [ "xdebug" ];
  languages.php.ini = ''
    xdebug.mode = debug
    xdebug.discover_client_host = 1
    xdebug.client_host =

Use MariaDB instead of MySQL

// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

  services.mysql.package = pkgs.mariadb;

Use customized MySQL port

// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

  services.mysql.settings = {
    mysqld = {
      port = 33881;

Use customized VirtualHosts port for Caddy

Use customized Adminer port

// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

  services.adminer.listen = "";

Known issues

Manually reloading devenv

If you decided against using direnv, keep in mind that on every change to the *.nix files you need to manually reload the environment. Run exit to quit the current devenv shell and enter the shell again to reload:

devenv shell

Direnv slow in big projects

The bigger your project directory is getting over time (e.g., cache files piling up), the slower direnv will be. This is a known issue, and the devenv developers are working on a solution.

Devenv slows down with big code repositories #257

Fail to start Redis with locale other than en_US

14:04:52 redis.1           | 364812:M 07 Nov 2023 14:04:52.999 # Failed to configure LOCALE for invalid locale name.

You can export a different locale to your shell with the following command:

export LANG=en_US.UTF8;


How do I clean up devenv?

Periodically run devenv gc to remove orphaned services, packages and processes and free-up disk space.

How do I access the database?

The MySQL service is exposed under its default port 3306, see default services.

Be aware that you cannot connect using the localhost socket. Instead, you must use

Where is the database stored?

The database is stored in the <PROJECT_ROOT>/.devenv/state/mysql directory.

Where do I find available packages?

The NixOS package search is a good starting point.

Where do I find the binaries?

The binaries can be found in the <PROJECT_ROOT>/.devenv/profile/bin directory.

This comes in handy if you want to configure interpreters in your IDE.

How do I stop all processes at once?

In case you can't find and stop running devenv processes, you can use the following command to kill them:

kill $(ps -ax | grep /nix/store  | awk '{print $1}')

Are you unable to access in your Browser?

Try using http://localhost:8000 instead. This mostly applies to when using WSL2.

Are you looking for a full test setup with demo data?

Run the below command:

composer setup && APP_ENV=prod bin/console framework:demodata && APP_ENV=prod bin/console dal:refresh:index