---
title: .moon/toolchains
toc_max_heading_level: 6
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import HeadingApiLink from '@site/src/components/Docs/HeadingApiLink';
import RequiredLabel from '@site/src/components/Docs/RequiredLabel';
import VersionLabel from '@site/src/components/Docs/VersionLabel';

The `.moon/toolchains.*` file configures the toolchain and the workspace development environment.
This file is _optional_.

Managing tool version's within the toolchain ensures a deterministic environment across any machine
(whether a developer, CI, or production machine).

## `extends`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#extends" />

Defines one or many external `.moon/toolchains.*`'s to extend and inherit settings from. Perfect for
reusability and sharing configuration across repositories and projects. When defined, this setting
must be an HTTPS URL _or_ relative file system path that points to a valid YAML document!

```yaml title=".moon/toolchains.yml" {1}
extends: 'https://raw.githubusercontent.com/organization/repository/master/.moon/toolchains.yml'
```

:::caution

Settings will be merged recursively for blocks, with values defined in the local configuration
taking precedence over those defined in the extended configuration.

:::

## `moon`<VersionLabel version="1.29.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#moon" />

Configures how moon will receive information about latest releases and download locations.

### `manifestUrl`

<HeadingApiLink to="/api/types/interface/MoonConfig#manifestUrl" />

Defines an HTTPS URL in which to fetch the current version information from.

```yaml title=".moon/toolchains.yml" {2}
moon:
  manifestUrl: 'https://proxy.corp.net/moon/version'
```

### `downloadUrl`

<HeadingApiLink to="/api/types/interface/MoonConfig#downloadUrl" />

Defines an HTTPS URL in which the moon binary can be downloaded from. The download file name is
hard-coded and will be appended to the provided URL.

Defaults to downloading from GitHub: https://github.com/moonrepo/moon/releases

```yaml title=".moon/toolchains.yml" {2}
moon:
  downloadUrl: 'https://github.com/moonrepo/moon/releases/latest/download'
```

## `proto`<VersionLabel version="1.39.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#proto" />

Configures how moon integrates with and utilizes [proto](/proto).

### `version`

<HeadingApiLink to="/api/types/interface/ProtoConfig#version" />

The version of proto to install and run toolchains with. If proto or this version of proto has not
been installed yet, it will be installed automatically when running a task.

```yaml title=".moon/toolchains.yml" {2}
proto:
  version: '0.51.0'
```

## Shared

The following settings are available and shared across all toolchains. Run
`moon toolchain info <toolchain>` for all available settings for a specific toolchain.

### `inheritAliases`<VersionLabel version="2.1.0" />

When enabled, will inherit [aliases for projects](../concepts/project#aliases) while the toolchain
is extending the project graph. An alias is typically derived from a `name` field in a toolchain
manifest file (`package.json`, `Cargo.toml`, etc). Defaults to `true`.

```yaml title=".moon/toolchains.yml"
javascript:
  inheritAliases: false
```

### `installDependencies`<VersionLabel version="2.1.0" />

When enabled and running a task, will automatically install toolchain dependencies if the lockfile,
manifest, or environment has changed changed since the last run. This is achieved through the
[`InstallDependencies` action](../how-it-works/action-graph). Defaults to `true`.

```yaml title=".moon/toolchains.yml"
javascript:
  installDependencies: false
```

### `plugin`

Configures the location of the `.wasm` plugin file that moon will use to run this toolchain.
Supports `file://` (relative from `.moon`), `https://`, and `github://` protocols.
[Learn more about plugin locators](../guides/wasm-plugins#configuring-plugin-locations).

```yaml title=".moon/toolchains.yml"
custom-toolchain:
  plugin: 'file://../path/to/plugin.wasm'
```

> This field is not required for built-in toolchains. However, it can be configured to override the
> built-in plugin if you want to use your own implementation.

### `versionFromPrototools`<VersionLabel version="2.0.0" />

When a toolchain supports the `version` setting, this setting controls whether the version will be
inherited from the root `.prototools` configuration file. This is useful for sharing a single
version across multiple toolchains, and only having to update it in one place.

When `false`, doesn't inherit a version. When `true`, matches the version specified in `.prototools`
using the same toolchain identifier. Otherwise a string can be provided to specify a proto-specific
identifier. Defaults to `true`.

> Keeping versions in `.prototools` also pairs well with [Renovate](../guides/renovate), which can
> update them automatically.

```yaml title=".moon/toolchains.yml"
node:
  versionFromPrototools: 'nodejs'
```

```toml title=".prototools"
nodejs = "~24"
```

## Go

## `go`

Run `moon toolchain info go` for all available settings.

## JavaScript

## `javascript`

Run `moon toolchain info javascript` for all available settings.

## `bun`

Run `moon toolchain info bun` for all available settings.

:::info

This toolchain requires the [`javascript`](#javascript) toolchain to also be enabled.

:::

## `deno`

Run `moon toolchain info deno` for all available settings.

:::info

This toolchain requires the [`javascript`](#javascript) toolchain to also be enabled.

:::

## `node`

Run `moon toolchain info node` for all available settings.

:::info

This toolchain requires the [`javascript`](#javascript) toolchain to also be enabled.

:::

## `npm`

Run `moon toolchain info npm` for all available settings.

:::info

This toolchain requires the [`node`](#node) toolchain to also be enabled.

:::

## `pnpm`

Run `moon toolchain info pnpm` for all available settings.

:::info

This toolchain requires the [`node`](#node) toolchain to also be enabled.

:::

## `yarn`

Run `moon toolchain info yarn` for all available settings.

:::info

This toolchain requires the [`node`](#node) toolchain to also be enabled.

:::

## `typescript`

Run `moon toolchain info typescript` for all available settings.

## Python

## `unstable_python`

Run `moon toolchain info unstable_python` for all available settings.

## `unstable_pip`

Run `moon toolchain info unstable_pip` for all available settings.

:::info

This toolchain requires the [`unstable_python`](#unstable_python) toolchain to also be enabled.

:::

## `unstable_poetry`

Run `moon toolchain info unstable_poetry` for all available settings.

:::info

This toolchain requires the [`unstable_python`](#unstable_python) toolchain to also be enabled.

:::

## `unstable_uv`

Run `moon toolchain info unstable_uv` for all available settings.

:::info

This toolchain requires the [`unstable_python`](#unstable_python) toolchain to also be enabled.

:::

## Ruby

## `unstable_ruby`

Run `moon toolchain info unstable_ruby` for all available settings.

## Rust

## `rust`

Run `moon toolchain info rust` for all available settings.
