---
title: Environment Variables | Shopware Community Hub
description: >-
Learn how to configure, override, and manage environment variables in Shopware
for different environments.
canonical_url: 'https://hub.shopware.com/learn/unit/environment-variables'
---
# Environment Variables
- Know where environment variables are stored.
- Understand how to use different `.env` files.
- Learn the common environment variables in Shopware.
- Recognize if an environment variable is missing.
# Environment Variables
Before writing any code, it's important to understand **why** environment variables exist and how to use them. In Shopware and also in any Symfony project, environment variables are the foundation for **flexible and secure configuration**. They allow you to:
- Separate **code** from **configuration**.
- Manage **different environments** (e.g., development, staging, production).
- Store **sensitive information** (e.g., database credentials, API keys, etc.) outside your codebase.
This helps you ensure that your project remains both **secure** and **portable**
## Environment Files Overview
Every Symfony project, including Shopware, uses `.env` files to store environment variables. Environment variables are key-value pairs that define configuration such as database credentials, API keys, or URLs outside your codebase. You can create multiple `.env` files for different environments:
| File Name | Purpose |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `.env` | Default file. Contains the default values for the environment variables. Used as template for others. |
| `.env.local` | Developer-specific overrides (e.g., local DB credentials). |
| `.env.prod.local` | Overrides for **production** configuration. Contains the values for the environment variables that are specific to the production environment. |
| `.env.test.local` | Overrides for **testing** configuration. Used in environments running tests (unit tests, integration tests, application-tests). |
In modern Symfony/Shopware projects, the `.env` file is usually **committed to version control** and acts as a baseline with **non-sensitive defaults**. Do **not** put real secrets into `.env`. Instead, store secrets and machine/environment-specific overrides in `.env.local` / `.env.*.local` (which are typically excluded via `.gitignore`) or provide them via your hosting environment / secret management solution.
When another developer clones the repository, they can copy the `.env` file to `.env.local` and define their own credentials and secrets **without exposing sensitive data in version control**.
You can find more information about environment variables in the [official Symfony documentation](https://symfony.com/doc/current/configuration.html#overriding-environment-values-via-env-local).
Never commit files containing credentials or secrets (like the `.env.local` file) to version control. **Always keep sensitive data out of repositories.**
## Real-World Example: MAILER_DSN
A common change within the `.env` file is the `MAILER_DSN` variable. Let's say your shop is running in production, and you want to send emails to your customers. You can set the `MAILER_DSN` variable to use the **SMTP** mailer to send emails. This way, you can send emails to your customers without any additional setup.
You can set the `MAILER_DSN` variable in the `.env.prod.local` file: Open the `.env.prod.local` file and add or adjust the following line:
```bash
MAILER_DSN=smtp://username:password@smtp.gmail.com:587?encryption=tls&auth_mode=login
```
And clear the cache by running the following command in your shop's root directory:
```bash
bin/console cache:clear
```
Now your Shopware shop will use Gmail's SMTP server to send emails.
Even though Shopware allows email settings via the Admin Panel (Settings -> Email Settings), it's recommended to set the MAILER_DSN in the `.env` file, especially for production environments, to ensure consistency and to prevent accidental overwrites.
Now that you have seen a practical example, let's take a closer look at the most common environment variables in Shopware.
### Environment Variables
Below you will find the common environment variables.
| Variable | Explanation |
|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| APP_ENV | Specifies the current environment, e.g., `dev`, `prod`, `test`. Affects caching, logging, error pages, etc. |
| APP_URL | The accessible URL of the shop. Important for generated links and redirects. |
| APP_SECRET | Used internally for hashes, tokens, etc. Should not be changed unless intentional, otherwise sessions and other feature may break. |
| INSTANCE_ID | Unique ID of the Shopware installation. Used for the shop and plugin verification. |
| DATABASE_URL | Connection URL for the MySQL or MariaDB database. Format `mysql://user:password@host:port/databasename`. |
| MAILER_DSN | Configuration for sending emails via Symfony Mailer. Default `null://localhost`. |
| SHOPWARE_ES_ENABLED | Enables/Disables OpenSearch/Elasticsearch. Default `0` |
| SHOPWARE_HTTP_CACHE_ENABLED | Enable/Disable the HTTP cache. Default `1`. |
| BLUE_GREEN_DEPLOYMENT | Enables special mechanisms for deployments in production environments. Default `0`. |
If you want to see the full list of the environment variables, go to this [official document](https://developer.shopware.com/docs/guides/hosting/configurations/shopware/environment-variables.html).
## Symfony Mailer
The Symfony Mailer component is used to send emails from the application. It can be configured to use different mailers for sending emails. The default mailer is the `null` mailer, which does not send any emails. This is a good choice for development environments, as it does not require any additional setup.
```text
# Default mailer
MAILER_DSN=null://null
```
The most common mailer is the `smtp` mailer, which sends emails using an SMTP server. This is a good choice for production environments, as it is fast and reliable.
Here is an example of a free and easy to set up SMTP server with GMAIL:
```text
MAILER_DSN=smtp://username:password@smtp.gmail.com:587?encryption=tls&auth_mode=login
```
Using a private email server is not recommended in production. It is better to use a [third party email provider](https://symfony.com/doc/current/mailer.html#using-a-3rd-party-transport).
## Other Environment Variables
If you want to check out the other environment variables, you can find them in the official [Developer documentation](https://developer.shopware.com/docs/guides/hosting/configurations/shopware/environment-variables.html#environment-variables).
## Summary
In this learning unit, you have learned:
- Where environment variables are stored and how to manage them across different environments.
- How to use different **`.env`** files.
- The common environment variables in Shopware.
- How to configure email settings using the **Symfony Mailer** and **`MAILER_DSN`**.
- Why it's recommended to manage sensitive settings via environment variables instead of the administration panel.
- Where to find the full list of environment variables in the official documentation.
With this knowledge, you can confidently configure and manage your Shopware environments for development, staging, and production.