---
title: Configuration overview
description: Configure Melos using the `melos.yaml` file.
---

# Configuration Overview

Every project requires a `melos.yaml` project in the root. The below outlines
all the configurable fields and their purpose.

Additionally, projects may include a `melos_overrides.yaml` file to override any
`melos.yaml` field. This is useful for making untracked customizations to a
project.

## name

<Warning>Required</Warning>

The name of this project for display purposes within IO environments and IDEs.

```yaml
name: My Awesome Project
```

## repository

The URL of the git repository that contains the Melos workspace.

Supported hosts:

- GitHub
- GitLab (https://gitlab.com)

```yaml
repository: https://github.com/invertase/melos
```

When using a self-hosted GitHub or GitLab instance, you can specify the
repository location like this:

```yaml
repository:
  type: gitlab
  origin: https://gitlab.example.dev
  owner: invertase
  name: melos
```

## sdkPath

Path to the Dart/Flutter SDK that should be used.

Relative paths are resolved relative to the `melos.yaml` file.

To use the system-wide SDK, provide the special value "auto".

If the SDK path is specified though multiple mechanisms, the precedence from
highest to lowest is:

1. `--sdk-path` global command line option
2. `MELOS_SDK_PATH` environment variable
3. `sdkPath` in `melos.yaml`

```yaml
sdkPath: .fvm/flutter_sdk
```

## packages

<Warning>Required</Warning>

A list of paths to local packages that are included in the Melos workspace. Each
entry can be a specific path or a [glob] pattern.

```yaml
packages:
  # Include the package in the workspace root.
  - .
  # Include all packages inside the `packages` directory that are direct children.
  - packages/*
  # Include all packages inside the `packages` directory and all descendants.
  - packages/**
```

<Info>
  You can also reduce the scope of packages on a per-command basis via the
  [`--scope` filter](/filters#--scope) flag.
</Info>

Avoid recursive whildcards (`**`) as they require walking large parts of the
file system and can be slow. If you have packages at multiple levels of depth,
consider using multiple patterns instead:

```yaml
packages:
  - packages/*
  - packages/*/example
```

## ignore

A list of paths to local packages that are excluded from the Melos workspace.
Each entry can be a specific path or a [glob] pattern.

```yaml
ignore:
  # e.g. ignore example apps
  - 'packages/**/example'
```

<Info>
  You can also expand the scope of packages on a per-command basis via the
  [`--scope` filter](/filters#--scope) flag.
</Info>

## ide/intellij

Configuration realting to IntelliJ IDE support.

### enabled

Whether to generate IntelliJ IDEA config files to improve the developer
experience when working in a Melos workspace.

The default is `true`.

```yaml
ide:
  intellij:
    enabled: false
```

### moduleNamePrefix

Used when generating IntelliJ project modules files. This value specifies a
string to prepend to a package's IntelliJ module name. Use this to avoid name
collisions with other IntelliJ modules you may already have in place.

The default is 'melos\_'.

## scripts

Define custom scripts that can be executed in the workspace via the
[`melos run`](/commands/run) command.

Learn more about defining scripts [here](/configuration/scripts).

## command/bootstrap

Configuration for the `bootstrap` command.

### dependencyOverridePaths

A list of paths to local packages realtive to the workspace directory that
should be added to each workspace package's dependency overrides. Each entry can
be a specific path or a [glob] pattern.

**Tip:** External local packages can be referenced using paths relative to the
workspace root.

```yaml
dependencyOverridePaths:
  - '../external_project/packages/**'
```

### runPubGetInParallel

Whether to run `pub get` in parallel during bootstrapping.

The default is `true`.

### runPubGetOffline

Whether to attempt to run `pub get` in offline mode during bootstrapping.

Useful in closed network environments with pre-populated pubcaches.

The default is `false`.

## command/version

Configuration for the `version` command.

### message

A template for the commit message, that is generated by `melos version`.

Templates must use mustache syntax and have the following variables available:

- `new_package_versions`: A list of the versioned packages and their new
  versions.

The default is:

```
chore(release): publish packages

{new_package_versions}
```

```yaml
command:
  version:
    message: |
      chore: cut package releases 🎉

      {new_package_versions}
```

### branch

If specified, prevents `melos version` from being used inside branches other
than the one specified.

```yaml
command:
  version:
    branch: main
```

### includeScopes

Whether to include conventional commit scopes in the generated CHANGELOG.md.
Defaults to `true`.

```yaml
command:
  version:
    includeScopes: false
```

### includeCommitId

Whether to add short commit ids to commits (no links) in the CHANGELOG.md that
is generated by `melos version`.

```yaml
command:
  version:
    includeCommitId: true
```

### linkToCommits

Whether to add links to commits in the CHANGELOG.md that is generated by
`melos version`. Defaults to `true` if `repository` is specified.

Enabling this option, requires
[`repository`](/configuration/overview#repository) to be specified.

```yaml
command:
  version:
    linkToCommits: false
```

### workspaceChangelog

Whether to additionally build a CHANGELOG.md at the root of the workspace when
running `melos version`. Defaults to `true`.

```yaml
command:
  version:
    workspaceChangelog: false
```

### changelogs

Configure aggregate changelogs which document the changes made to multiple
packages.

```yaml
command:
  version:
    changelogs:
      - path: FOO_CHANGELOG.md
        description: |
          All notable changes to foo packages will be documented in this file.
        packageFilters:
          scope: foo_*
```

#### path

The path to the changelog file relative to the workspace root.

#### packageFilters

Package filters to match packages that should be included in the changelog.

See [Filtering Packages](/filters) for all available filters.

<Warning>
  The filter names in `packageFilters` are camel cased. For example, for the
  equivalent of the command line option `--file-exists` use `fileExists`.
</Warning>

#### description

A description to include at the top of the changelog.

If you change this value, you will need to manually update the changelog file to
reflect the new description.

### updateGitTagRefs

Whether to update package version tags in git dependencies of dependents when
versioning packages.

See the
[automated releases documentation](/guides/automated-releases#git-hosted-packages)
for more information.

```yaml
command:
  version:
    updateGitTagRefs: true
```

### releaseUrl

Whether to generate and print a link to the prefilled release creation page for
each package after versioning. Defaults to `false`.

[glob]: https://docs.python.org/3/library/glob.html

### fetchTags

Whether to fetch tags from the `origin` remote before versioning. Defaults to
`true`.

```yaml
command:
  version:
    fetchTags: false
```