はじめに (対象読者・この記事でわかること)

この記事は、macOS の開発環境を構築・保守しているエンジニア、特に Homebrew を中心にパッケージ管理を行っている方を対象としています。Node.js を Homebrew 経由でインストールしたくないが、Yarn は常に最新に保ちたいというニーズに応える内容です。本記事を読むことで、以下が実現できるようになります。

  • Homebrew だけで Yarn のバージョンを確認・アップグレードする方法
  • Node.js をインストールせずに Yarn の実行環境を整える手順
  • トラブルシューティングのポイントとベストプラクティス

この手法は、グローバルに Node を別途管理している環境や、プロジェクト単位で nvm などを使用しているケースでも安全に適用できます。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • macOS のターミナル操作に慣れていること
  • Homebrew の基本的な使い方（brew install, brew list など）が分かること
  • Yarn の基本概念（パッケージマネージャとしての役割）を概ね理解していること

Yarn のアップグレードが必要になる背景と概念

Node.js と Yarn は密接に連携しますが、Yarn は Node がインストールされていれば実行可能です。Homebrew では brew install node と同時に Yarn がインストールされるケースが多く、結果として不要な Node のバイナリまで持ち込んでしまうことがあります。特に以下のようなケースで「Node だけは別管理したい」ニーズが生まれます。

  1. プロジェクト別の Node バージョン管理
    nvm や asdf でプロジェクトごとに Node バージョンを切り替えている場合、Homebrew が管理するグローバル Node と衝突しやすくなる。

  2. 軽量環境の構築
    Docker コンテナや CI 環境で最小限のバイナリだけを入れたいとき、不要な Node を省くことでイメージサイズが削減できる。

  3. セキュリティ・ポリシー
    社内のセキュリティ基準でグローバルインストールが制限されているケースでは、Node を直接インストールできないことがある。

Yarn 自体は「スタンドアロン」モードで動作可能です。つまり、Node がシステムに無くても、Yarn が内部で必要とする Node ランタイム（node_modules/.bin 以下に同梱される）を自動的に取得してくれます。この特性を利用すれば、Homebrew で Yarn だけを管理し、Node のインストールは別ツール（nvm, asdf, volta など）に委ねることができます。

Homebrew のインストールオプションを活用する

Homebrew の Formula には「オプション」や「依存関係の除外」機能がありますが、公式の Yarn Formula は Node を必須依存として定義しています。そのため、brew install yarn だけだと Node が自動で入ります。そこで取るべきアプローチは 2 つあります。

  • cask パッケージ（Yarn Classic） を利用する
  • corepack 経由で Yarn を管理する

次章では、実際にこれらの手順をコードサンプル付きで詳しく解説します。

Homebrew だけで Yarn をアップグレードする具体的手順

ステップ 1: 現在インストールされている Yarn と Node の状態を確認

まずはターミナルで以下のコマンドを実行し、現在のバージョンとインストール元を把握します。

Bash

# Yarn のバージョンとインストール経路
yarn -v
which yarn

# Node のバージョンとインストール経路（不要なら削除対象）
node -v
which node

which yarn が /usr/local/bin/yarn など Homebrew のパスを指していれば、Homebrew 管理下です。一方、node が同じく Homebrew パスにある場合は、不要な Node が入っている可能性があります。

ステップ 2: Node を安全に除去（必要なら）

Homebrew でインストールされた Node を削除するには次のコマンドを実行します。

Bash

brew uninstall node

注意点
- プロジェクトで nvm や asdf から Node を使用している場合、上記コマンドは影響しません。
- ただし、Homebrew が管理する Yarn が Node に依存していると、Yarn の実行時にエラーになる可能性があります。その場合は次のステップで Yarn を再インストールします。

ステップ 3: Yarn を再インストール（Node 依存を除外）

Homebrew の公式 Formula では Node が依存として必須ですが、代替手段として Yarn Classic（cask）を利用すると Node 依存が除外されます。

Bash

# 既存の Yarn をアンインストール
brew uninstall yarn

# Yarn Classic（cask）をインストール
brew install --cask yarn

brew info --cask yarn を確認すると、/Applications/Yarn.app がインストールされ、実行ファイルは /usr/local/bin/yarn へシンボリックリンクされます。このバイナリは内部に Node ランタイムを同梱しているため、システムに別途 Node がなくても動作します。

ステップ 4: Yarn のバージョンを指定してアップグレード

cask 版 Yarn は Homebrew の brew upgrade コマンドで自動的に最新バージョンに更新されます。手動で特定バージョンにしたい場合は brew install --cask yarn@<version> のように指定します。

Bash

# 最新版にアップグレード
brew upgrade --cask yarn

# 特定バージョン（例: 1.22.19）をインストールしたい場合
brew install --cask yarn@1.22.19

インストール後は再度バージョンを確認して、期待通りに更新されているか検証します。

Bash

yarn -v

ステップ 5: corepack を利用した Yarn 管理（別アプローチ）

Node.js 16 以降では corepack が標準で同梱されており、Yarn のバージョン管理を corepack コマンドだけで完結できます。これを利用すれば、Homebrew で Node を入れずに Yarn のバージョン切替が可能です。

Bash

# corepack 有効化（Node がインストールされている前提）
corepack enable

# Yarn を最新版に自動インストール
corepack prepare yarn@stable --activate

※この方法は Node がシステムにインストールされている 前提です。Node が必要な場合は nvm などでローカルにインストールし、グローバルの Homebrew Node はインストールしない構成にすると良いでしょう。

ハマった点やエラー解決

エラー例 1: yarn: command not found

  • 原因: Homebrew の brew install --cask yarn 後にパスが更新されていない。
  • 解決策: ターミナルを再起動するか、source ~/.zshrc（使用シェルに合わせて）で環境変数をリロードする。

エラー例 2: node: command not found と表示され Yarn が起動しない

  • 原因: cask 版 Yarn がシステムにインストールされた Node を参照しようとしている。
  • 解決策: brew uninstall node 後、再度 brew install --cask yarn を実行すると、内部同梱の Node が使用される。

エラー例 3: brew upgrade --cask yarn が「No updates are available」と表示され続ける

  • 原因: Homebrew の cask キャッシュが古い。
  • 解決策: 以下のコマンドでキャッシュをクリアし、再度チェックする。
Bash

brew cleanup
brew update
brew upgrade --cask yarn

まとめのポイント

  • Homebrew で Node を入れずに Yarn を管理したい場合は、cask 版 Yarn (Yarn Classic) の利用が最もシンプル。内部に Node が同梱されているため別途 Node インストールが不要。
  • 既に Homebrew で Node が入っている環境は brew uninstall node で安全に除去できる。Yarn が動かなくなったら再インストールすれば解決。
  • corepack を併用すれば、Node が別途管理されている環境でも Yarn のバージョン切替が容易になる。

まとめ

本記事では、Homebrew だけで Node をインストールせずに Yarn を安全にアップグレードする手順を解説しました。

  • cask 版 Yarn を使うことで Node 依存を排除し、スタンドアロンで最新バージョンを取得可能。
  • 既存の Node は brew uninstall node で削除し、Yarn を再インストールすれば環境がクリーンになる。
  • corepack を併用すれば、Node 管理ツールと組み合わせた柔軟なバージョンコントロールが実現できる。

これにより、プロジェクトごとに異なる Node バージョンを保ちつつ、Yarn の管理を統一でき、開発・CI 環境の構築が格段に楽になります。今後は、Yarn のプラグイン活用や、Zero‑Install 環境の構築についても記事にしていく予定です。

参考資料