The .env file is the control center for any Shopware installation. Located in your root directory, it holds the settings that determine how your store connects to databases, serves pages, and operates in different environments. Get these settings right and your store runs smoothly; misconfigure them and you'll chase obscure errors across your codebase.
Key Configuration Parameters
APP_URL** sets the base address where your store is accessible. This must include the protocol (http or https) and match your domain exactly. During development on your local machine, this might be `http://localhost` or a custom local URL. In production, this must reflect your live domain.
DATABASE_URL** stores your database connection information. The format requires your database name inserted between the connection details. Ensure credentials match exactly — mismatches here produce errors that are difficult to trace back to this file.
COMPOSER_HOME** defines the path to your Composer cache directory. The correct format is your root directory path followed by `/var/cache/composer`. If this path is incorrect, dependency management fails.
Dev vs. Production: Quick Decision Checklist
Use this checklist to configure your environment correctly:
- [ ] **Development Mode
- APP_ENV = dev
- SHOPWARE_HTTP_CACHE_ENABLED = 0
- Purpose: Verbose errors, active debugging, fresh content on every request
- [ ] **Production Mode
- APP_ENV = prod
- SHOPWARE_HTTP_CACHE_ENABLED = 1
- Purpose: Optimized performance, suppressed error details, full-page caching enabled
Switching between these modes is where many developers run into confusion. A configuration that works perfectly in development may cause unexpected behavior in production — usually because caching behaves differently between modes.
Caching Behavior
The `SHOPWARE_HTTP_CACHE_ENABLED` parameter has only two valid values. Setting it to `0` disables HTTP caching, which is appropriate during development when you need to see changes immediately. Setting it to `1` enables full-page caching, which significantly improves storefront load times in production environments.
Hidden Files
If you don't see the .env file in your root directory, enable hidden file display in your file manager. On most systems, pressing Ctrl+H toggles this visibility. The file starts with a dot, which is why it may appear hidden by default.
Why It Matters
The settings in your .env file affect every aspect of your store's operation. APP_URL mismatches cause broken asset links and redirect loops. Incorrect DATABASE_URL values prevent your store from loading entirely. Wrong caching settings either slow down development or create production environments where content updates don't appear.
For teams expanding Shopware into new European markets, understanding these configuration fundamentals becomes even more critical. A misconfigured environment file is one of the most common causes of deployment failures and unexpected behavior.
Key takeaways
- APP_URL must include the full protocol and domain — mismatches break links and redirects
- Set APP_ENV to dev during development and prod in production — never mix these
- Enable HTTP caching (set to 1) only when deploying to production
- Always clear your cache after modifying .env settings to ensure changes take effect
Frequently asked questions
Where is the Shopware .env file located?
The .env file is in your Shopware installation's root directory. If you don't see it, press Ctrl+H to show hidden files.
How do I configure the store URL?
Update the APP_URL parameter in the .env file to match your desired domain, including the protocol (http or https).
What does SHOPWARE_HTTP_CACHE_ENABLED control?
This setting toggles HTTP caching. Use 0 for development (caching disabled) and 1 for production (caching enabled).
How do I switch between development and production modes?
Change the APP_ENV value: set it to dev for development or prod for production. Remember to also adjust your caching setting accordingly.
What happens after I modify the .env file?
After changing .env settings, clear the cache so Shopware loads the new configuration. You can do this via CLI or by clearing the var/cache directory.