---
contributors: Esther Agbaje, Kevin Lewis
description: Discover how to install extensions to your Directus project.
---

<script setup lang="ts">
import { data as packages } from '@/data/packages.data.js';
</script>

# Installing Extensions

There are three ways to install extensions to your Directus project:

1. Installing via the Directus Marketplace
2. Installing via the npm Registry
3. Installing via the Extensions Directory

## Installing via the Directus Marketplace

Extensions in the Directus Marketplace Registry are made available via the Marketplace section in the Settings Module.

By default, App Extensions and [Sandboxed Extensions](/extensions/sandbox/introduction) are available from the
Marketplace in all Directus projects (Directus Professional and Enterprise Cloud, and self-hosted).

<Card
	title="User Guide"
	text="Learn more about installing extensions from the Directus Marketplace."
	url="/user-guide/marketplace/overview"
	style="margin: 1rem 0"
/>

<Card
	title="Publishing Guide"
	text="Learn more about publishing extensions to the Directus Marketplace."
	url="/extensions/marketplace/publishing"
/>

## Installing via the npm Registry

Extensions can be installed in a Directus project from the npm registry. Before you begin, ensure you have a
[self-hosted instance of Directus](/self-hosted/quickstart) via Docker installed on your system.

**1. Modify docker-compose.yml**

Open the `docker-compose.yml` file of your project and replace the `image` option with a `build` section:

```yaml-vue
image: directus/directus:{{ packages.directus.version.major }}.x.y // [!code --]
build: // [!code ++]
  context: ./ // [!code ++]
```

This allows you to build a customized Docker Image with the added extensions.

**2. Create a Dockerfile**

At the root of your project, create a `Dockerfile` if one doesn't already exist and add the following:

```Dockerfile-vue
FROM directus/directus:{{ packages.directus.version.major }}.x.y

USER root
RUN corepack enable
USER node

RUN pnpm install directus-extension-package-name
```

::: tip Extension Name

Remember to replace `directus-extension-package-name` with the name of the extension's npm package.

:::

**3. Build the Docker Image**

Build your Docker image:

```bash
docker compose build
```

**4. Start the Docker Container**

Start your Docker container:

```bash
docker compose up
```

On startup, you'd see that Directus will automatically load any extension installed in the previous steps.

## Installing via the Extensions Directory

To locally install extensions, copy the files generated by the `directus-extension build` command into the `extensions`
folder located at the root of your Directus project.

::: warning Configurable Folders

The path to the built extension as well as the extensions directory are configurable and may be located elsewhere.

:::

Before you begin, ensure you have a [self-hosted instance of Directus](/self-hosted/quickstart) via Docker installed on
your system.

**1. Create an Extensions Folder**

At the root of your project, create an `extensions` folder if one doesn't already exist to house your extensions.

**2. Add your new extension into the extensions folder**

Move the `package.json` file along with the output from the `dist/` folder into a new folder in the extensions folder
you created earlier.

Your folder structure should look like this:

```
extensions/
  <extension-name>/
    dist/
      index.js
    package.json
  ...
```

**3. Update Docker Compose File**

Open your `docker-compose.yml` file and add a volume to mount your extensions folder into the Docker container:

```yaml
volumes:
  - ./extensions:/directus/extensions/
```

**4. Start the Docker Container**

Start your Docker container:

```bash
docker compose up
```

You should see that your extension has been successfully loaded into the Docker container. Now, go ahead to customize
your extension by making changes to the `src` folder within your extension directory.

::: tip Automatically Reload Extensions

To automatically reload extensions every time you make a change, without having to restart Directus, in your
`docker-compose.yml` file, set `EXTENSIONS_AUTO_RELOAD=true`.

:::