6.4 (current)


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:
Windows (WSL2)
sh <(curl -L https://nixos.org/nix/install)
sh <(curl -L https://nixos.org/nix/install) --daemon
sh <(curl -L https://nixos.org/nix/install) --no-daemon
docker run -it nixos/nix


Next, install Cachix to speed up the installation:
nix-env -iA cachix -f https://cachix.org/api/v1/install
Before installing devenv, instruct Cachix to use the devenv cache:
cachix use devenv
The first time you run cachix use, you will be prompted a warning that you are not a trusted user.
This user doesn't have permissions to configure binary caches.
You can either:
a) ...
b) ...
When you encounter the above message, run:
echo "trusted-users = root ${USER}" | sudo tee -a /etc/nix/nix.conf && sudo pkill nix-daemon


Finally, install devenv:
nix-env -if https://github.com/cachix/devenv/tarball/v0.5
Before booting up your development environment, configure Cachix to use Shopware's cache:
cachix use shopware
By default, shopware/platform uses unfree software like Blackfire. To be able to use unfree software, you have to allow it:
mkdir -p ~/.config/nixpkgs
echo '{ allowUnfree = true; }' > ~/.config/nixpkgs/config.nix
You can find the whole installation guide for devenv in their official documentation:


Depending on whether you want to set up a fresh Shopware project or contribute to the Shopware core, choose between:
Symfony Flex
shopware/platform (Contribute)
If you are already using Symfony Flex, you require a Composer package to get a basic devenv configuration:
composer require devenv
This will create a basic devenv.nix file to enable devenv support for Shopware.
Clone shopware/platform and change into the project directory:
git clone [email protected]:shopware/platform.git
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.
Ensure to change your .env file to have the database connect using localhost's IP address instead of the default MySQL socket:
DATABASE_URL="mysql://shopware:[email protected]:3306/shopware?sslmode=disable&charset=utf8mb4"
With a new terminal, go 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:
composer setup


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 that 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:
The preferred way to install direnv on macOS is using Homebrew:
brew install direnv
apt install direnv
The installation instructions for other OS are available on direnv's official documentation.
Afterwards, add the following hook to your shell:
eval "$(direnv hook bash)"
eval "$(direnv hook zsh)"
direnv hook fish | source
The installation instructions for other OS are available on direnv's official documentation.
After you change into a project directory using devenv for the first time, you need to allow direnv to load the environment:
direnv allow

Default services

Here is an overview of services Shopware provides by default and how you can access them:
mysql://shopware:[email protected]:3306
Mailhog (SMTP)
Mailhog (Web UI)

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.
{ 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}
# Override an environment variable
env.APP_URL = "http://shopware.swag";
Refer to the official devenv documentation to get a complete list of all available services and their configuration possibilities:

Enable Blackfire

{ 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

{ pkgs, config, lib, ... }:
languages.php.package = pkgs.php.buildEnv {
extensions = { all, enabled }: with all; enabled ++ [ amqp redis blackfire grpc xdebug ];
extraConfig = ''
# Copy the config from devenv.nix and append the XDebug config
# [...]

Use MariaDB instead of MySQL

{ pkgs, config, lib, ... }:
services.mysql.package = pkgs.mariadb;

Known issues

Manually reloading direnv

If you decided against using direnv, keep in mind that on every change to the *.nix files you need to manually reload the environment:
direnv reload

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.


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.