---
title: Your First Shopware Plugin | Shopware Community Hub
description: >-
Create, install, activate, and verify a minimal Shopware plugin before
learning how plugin architecture and controllers work.
canonical_url: 'https://hub.shopware.com/learn/unit/your-first-shopware-plugin'
---
# Your First Shopware Plugin
- Create a minimal Shopware plugin with the CLI.
- Understand why Shopware needs `plugin:refresh` before installing a new plugin.
- Install and activate the plugin step by step.
- Verify the plugin in the CLI and the administration.
# Your First Shopware Plugin
Backend development in Shopware starts with a plugin. It gives your custom code its own place without changing Shopware core code.
In this learning unit, you create your first minimal plugin, register it in Shopware's plugin list, install and activate it, and verify the result in the CLI and the administration.
After this, you have a working base for the architecture and controller topics in the next units.
## Reminder: Prerequisites
Remember to have a **local Shopware 6.7** development environment with **PHP 8.3**.
If your shop setup is missing, complete the [Shopware Setup course](/learn/path/familiarize-with-shopware) first, then return to this learning path.
## Create a Minimal Plugin
Run this command in your shop root:
```shell
bin/console plugin:create AcademyFirstPlugin Academy
```
Answer **no** to all optional generators (controller, entities, storefront module, and so on). You only need the bare plugin skeleton.
This command creates a new plugin under `[shop_root]/custom/plugins/AcademyFirstPlugin`.
The first value, `AcademyFirstPlugin`, is the plugin name. The second value, `Academy`, is the PHP namespace prefix that Shopware writes into the generated plugin files. In this example, the main plugin class becomes `Academy\AcademyFirstPlugin`, and the Composer package name becomes `academy/academy-first-plugin`.
Before you continue, make sure the command finishes without errors and that the folder `custom/plugins/AcademyFirstPlugin` exists. If the command fails, your local setup is not ready yet. Check that you are in the shop root and that `bin/console` works before moving on.
### What Did You Create?
A Shopware plugin is a server-side extension based on Symfony's bundle system. It gives project-specific code its own place without changing Shopware core code.
In later units, plugins can contain services, controllers, subscribers, entities, templates, and other custom behavior. In this first unit, the plugin stays minimal.
## Install and Activate
Shopware keeps a list of available plugins in the database. After you create or copy a plugin into `[shop_root]/custom/plugins`, run `bin/console plugin:refresh` to synchronize that list with the current plugin files.
This makes `AcademyFirstPlugin` available as a known plugin name for the next commands:
```bash
bin/console plugin:refresh
```
Now install the plugin:
```bash
bin/console plugin:install AcademyFirstPlugin
```
After installation, activate it:
```bash
bin/console plugin:activate AcademyFirstPlugin
```
You can combine installation and activation in one command:
```bash
bin/console plugin:install AcademyFirstPlugin --activate
```
Finally, clear the cache so Shopware can work with the updated plugin state:
```bash
bin/console cache:clear
```
After you understand the separate steps, you can combine installation, activation, and cache clearing in one command:
```bash
bin/console plugin:install AcademyFirstPlugin --activate --clearCache
```
This shortcut does not replace `plugin:refresh`. Run `plugin:refresh` first when you have just created or copied a plugin.
## Verify the Plugin in the CLI
First, check the plugin status in the terminal:
```bash
bin/console plugin:list
```
You should see `AcademyFirstPlugin` with the value `Yes` in the columns `Installed` and `Active`.
## Verify the Plugin in the Administration
You can also verify the plugin in the Shopware administration.
If you followed the Shopware setup course, open the administration at:
```text
http://localhost:8000/admin
```
If your local shop uses a different URL, append `/admin` to that URL.
Log in with the default local credentials from the setup course:
- **Username:** `admin`
- **Password:** `shopware`
Then open **Extensions → My extensions**.
`AcademyFirstPlugin` appears in the extension list. You do not need to configure anything yet. At this point, the administration check only confirms that Shopware recognizes the plugin.
## Confirm the Result
Before moving on, confirm that all three checks work:
1. `plugin:list` shows `AcademyFirstPlugin` as installed and activated.
2. `AcademyFirstPlugin` appears under **My extensions** in the administration.
3. `bin/console cache:clear` has run without errors related to your plugin.
Which command installs and activates the plugin when used as a shortcut after `plugin:refresh`?
bin/console plugin:refresh --activate
bin/console plugin:install AcademyFirstPlugin --activate
bin/console plugin:create AcademyFirstPlugin --activate
## Summary
In this learning unit, you learned:
- How to create a minimal Shopware plugin with `plugin:create`.
- Why `plugin:refresh` is needed before Shopware can install a newly created plugin by name.
- How to install, activate, and clear the cache for a plugin step by step.
- How to verify the plugin in the CLI and in the Shopware administration.
You now have a working plugin that Shopware recognizes. This confirms that your environment is ready and gives you a safe starting point for the next learning unit, where you will learn how services, controllers, subscribers, and dependency injection fit into a plugin.