go.mod ファイルリファレンス

各 Go モジュールは、他のモジュールおよび Go のバージョンへの依存関係を含む、モジュールのプロパティを記述する go.mod ファイルによって定義されます。

これらのプロパティには以下が含まれます。

現在のモジュールのモジュールパス。これは、Go ツール（モジュールコードのリポジトリロケーションなど）によってモジュールをダウンロードできる場所である必要があります。これは、モジュールのバージョン番号と組み合わせることで、一意の識別子として機能します。また、モジュール内のすべてのパッケージのパッケージパスのプレフィックスでもあります。Go がモジュールをどのように検索するかについては、「Go モジュールリファレンス」を参照してください。
現在のモジュールが必要とする Go の最小バージョン。
現在のモジュールが必要とする他のモジュールの最小バージョンのリスト。
必要に応じて、必須モジュールを別のモジュールバージョンまたはローカルディレクトリに置き換える、または必須モジュールの特定のバージョンを除外するための指示。

go mod init コマンドを実行すると、Go は go.mod ファイルを生成します。次の例では、モジュールのモジュールパスを example/mymodule に設定して go.mod ファイルを作成します。

$ go mod init example/mymodule

go コマンドを使用して依存関係を管理します。これらのコマンドは、go.mod ファイルに記述されている要件が矛盾なく維持され、go.mod ファイルの内容が有効であることを保証します。これらのコマンドには、go get、go mod tidy、および go mod edit コマンドが含まれます。

go コマンドのリファレンスについては、「Command go」を参照してください。コマンドラインから go help command-name（例: go help mod tidy）と入力すると、ヘルプを取得できます。

こちらも参照

Go ツールは、依存関係の管理に使用する際に go.mod ファイルを変更します。詳細については、「依存関係の管理」を参照してください。
go.mod ファイルに関連する詳細と制約については、「Go モジュールリファレンス」を参照してください。

例

go.mod ファイルには、次の例に示すようなディレクティブが含まれています。これらはこのトピックの他の場所で説明されています。

module example.com/mymodule

go 1.14

require (
    example.com/othermodule v1.2.3
    example.com/thismodule v1.2.3
    example.com/thatmodule v1.2.3
)

replace example.com/thatmodule => ../thatmodule
exclude example.com/thismodule v1.3.0

module

モジュールのモジュールパスを宣言します。これはモジュールの一意の識別子（モジュールバージョン番号と組み合わせた場合）です。モジュールパスは、モジュールに含まれるすべてのパッケージのインポートプレフィックスになります。

詳細については、「Go モジュールリファレンス」の「module ディレクティブ」を参照してください。

構文

module module-path

module-path: モジュールのモジュールパス。通常は、Go ツールによってモジュールがダウンロードできるリポジトリの場所です。モジュールバージョン v2 以降の場合、この値は /v2 のようにメジャーバージョン番号で終わる必要があります。

例

次の例では、example.com はモジュールがダウンロードされるリポジトリドメインの代わりに使用されています。

v0 または v1 モジュールのモジュール宣言
```
module example.com/mymodule
```
v2 モジュールのモジュールパス
```
module example.com/mymodule/v2
```

注

モジュールパスは、モジュールを一意に識別する必要があります。ほとんどのモジュールでは、パスは go コマンドがコードを見つけることができる URL（またはコードへのリダイレクト）です。直接ダウンロードされることのないモジュールの場合、モジュールパスは、一意性を確保するために制御する単なる名前でも構いません。example/ というプレフィックスは、このような例での使用のために予約されています。

詳細については、「依存関係の管理」を参照してください。

実際には、モジュールパスは通常、モジュールソースのリポジトリドメインと、リポジトリ内のモジュールコードへのパスです。go コマンドは、モジュールユーザーに代わって依存関係を解決するためにモジュールバージョンをダウンロードする際に、この形式に依存します。

最初からモジュールを他のコードから利用可能にするつもりがない場合でも、リポジトリパスを使用することは、後で公開する場合にモジュールの名前を変更する必要を避けるためのベストプラクティスです。

最初にモジュールの最終的なリポジトリの場所がわからない場合は、一時的に安全な代替手段（所有するドメインの名前や制御する名前（会社名など））と、モジュールの名前またはソースディレクトリからのパスを検討してください。詳細については、「依存関係の管理」を参照してください。

たとえば、stringtools ディレクトリで開発している場合、一時的なモジュールパスは <会社名>/stringtools となる場合があります。次の例では、会社名 はあなたの会社名です。

go mod init <company-name>/stringtools

go

このディレクティブで指定された Go バージョンのセマンティクスを前提としてモジュールが記述されていることを示します。

詳細については、「Go モジュールリファレンス」の「go ディレクティブ」を参照してください。

構文

go minimum-go-version

minimum-go-version: このモジュール内のパッケージをコンパイルするために必要な Go の最小バージョン。

例

モジュールは Go バージョン 1.14 以降で実行する必要があります
```
go 1.14
```

注

go ディレクティブは、このモジュールを使用するために必要な Go の最小バージョンを設定します。Go 1.21 より前は、このディレクティブは推奨事項に過ぎませんでしたが、現在は必須要件です。Go ツールチェーンは、新しい Go バージョンを宣言するモジュールを使用することを拒否します。

go ディレクティブは、実行する Go ツールチェーンを選択するための入力となります。詳細については、「Go ツールチェーン」を参照してください。

go ディレクティブは新しい言語機能の使用に影響します

モジュール内のパッケージの場合、コンパイラは go ディレクティブで指定されたバージョンより後に導入された言語機能の使用を拒否します。たとえば、モジュールに go 1.12 ディレクティブがある場合、そのパッケージは Go 1.13 で導入された 1_000_000 のような数値リテラルを使用できません。
古い Go バージョンがモジュールのいずれかのパッケージをビルドし、コンパイルエラーが発生した場合、エラーはモジュールが新しい Go バージョン用に記述されていることを示します。たとえば、モジュールに go 1.13 があり、パッケージが数値リテラル 1_000_000 を使用しているとします。そのパッケージが Go 1.12 でビルドされた場合、コンパイラはコードが Go 1.13 用に記述されていることを示します。

go ディレクティブは go コマンドの動作にも影響します。

go 1.14 以降では、自動ベンダーリングが有効になる場合があります。ファイル vendor/modules.txt が存在し、go.mod と一致している場合、明示的に -mod=vendor フラグを使用する必要はありません。
go 1.16 以降では、all パッケージパターンは、メインモジュール内のパッケージおよびテストによって推移的にインポートされるパッケージのみに一致します。これは、モジュールが導入されて以来、go mod vendor によって保持されているパッケージのセットと同じです。それより低いバージョンでは、all はメインモジュール内のパッケージによってインポートされるパッケージのテスト、それらのパッケージのテストなども含まれます。
go 1.17 以降
- go.mod ファイルには、メインモジュール内のパッケージまたはテストによって推移的にインポートされるパッケージを提供する各モジュールに対して、明示的なrequire ディレクティブが含まれます。（go 1.16 以前では、間接的な依存関係は、最小バージョン選択が別のバージョンを選択する場合にのみ含まれていました。）この追加情報により、モジュールグラフのプルーニングと遅延モジュールローディングが可能になります。
- 以前の go バージョンよりも多くの // indirect 依存関係が存在する可能性があるため、間接的な依存関係は go.mod ファイル内の別のブロックに記録されます。
- go mod vendor は、ベンダー依存関係の go.mod および go.sum ファイルを省略します。（これにより、vendor のサブディレクトリ内での go コマンドの呼び出しが正しいメインモジュールを識別できるようになります。）
- go mod vendor は、各依存関係の go.mod ファイルからの go バージョンを vendor/modules.txt に記録します。
go 1.21 以降
- go 行は、このモジュールで使用するために必要な Go の最小バージョンを宣言します。
- go 行は、すべての依存関係の go 行以上である必要があります。
- go コマンドは、以前の古い Go バージョンとの互換性を維持しようとすることはなくなりました。
- go コマンドは、go.mod ファイルのチェックサムを go.sum ファイルに保持することについて、より注意深くなっています。

go.mod ファイルには、最大で 1 つの go ディレクティブを含めることができます。ほとんどのコマンドは、存在しない場合は現在の Go バージョンで go ディレクティブを追加します。

toolchain

このモジュールで使用する推奨 Go ツールチェーンを宣言します。モジュールがメインモジュールであり、デフォルトのツールチェーンが推奨ツールチェーンよりも古い場合にのみ有効になります。

詳細については、「Go ツールチェーン」および「Go モジュールリファレンス」の「toolchain ディレクティブ」を参照してください。

構文

toolchain toolchain-name

toolchain-name: 推奨 Go ツールチェーンの名前。標準のツールチェーン名は、go1.21.0 や go1.18rc1 のように、Go バージョン V に対して goV の形式を取ります。特殊な値 default は、自動ツールチェーン切り替えを無効にします。

例

Go 1.21.0 以降の使用を推奨
```
toolchain go1.21.0
```

注

toolchain 行が Go ツールチェーンの選択にどのように影響するかについては、「Go ツールチェーン」を参照してください。

godebug

このモジュールのメインパッケージに適用されるデフォルトの GODEBUG 設定を示します。これらはすべてのツールチェーンのデフォルトを上書きし、メインパッケージの明示的な //go:debug 行によって上書きされます。

構文

godebug debug-key=debug-value

debug-key: 適用する設定の名前。設定のリストとそれらが導入されたバージョンは、「GODEBUG History」にあります。
debug-value: 設定に提供される値。特に指定がない限り、0 は無効にし、1 は指定された動作を有効にします。

例

新しい 1.23 asynctimerchan=0 の動作を使用
```
godebug asynctimerchan=0
```
Go 1.21 からのデフォルトの GODEBUG を使用するが、古い panicnil=1 の動作を使用
```
godebug (
    default=go1.21
    panicnil=1
)
```

注

GODEBUG 設定は、現在のモジュールのメインパッケージとテストバイナリのビルドにのみ適用されます。モジュールが依存関係として使用される場合には影響しません。

後方互換性の詳細については、「Go、後方互換性、および GODEBUG」を参照してください。

require

モジュールを現在のモジュールの依存関係として宣言し、必要なモジュールの最小バージョンを指定します。

詳細については、「Go モジュールリファレンス」の「require ディレクティブ」を参照してください。

構文

require module-path module-version

module-path: モジュールのモジュールパス。通常は、モジュールソースのリポジトリドメインとモジュール名を連結したものです。モジュールバージョン v2 以降の場合、この値は /v2 のようにメジャーバージョン番号で終わる必要があります。
module-version: モジュールのバージョン。これは、v1.2.3 のようなリリースバージョン番号、または v0.0.0-20200921210052-fa0125251cc4 のような Go 生成の疑似バージョン番号のいずれかになります。

例

リリースバージョン v1.2.3 を要求する
```
require example.com/othermodule v1.2.3
```
Go ツールによって生成された疑似バージョン番号を使用して、リポジトリでまだタグ付けされていないバージョンを要求する
```
require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4
```

注

go get などの go コマンドを実行すると、Go はインポートされたパッケージを含む各モジュールに対して require ディレクティブを挿入します。モジュールがリポジトリでまだタグ付けされていない場合、Go はコマンドの実行時に生成する疑似バージョン番号を割り当てます。

replace ディレクティブを使用すると、リポジトリ以外の場所からモジュールを要求するように Go に指示できます。

バージョン番号の詳細については、「モジュールのバージョン番号付け」を参照してください。

依存関係の管理の詳細については、以下を参照してください。

tool

パッケージを現在のモジュールの依存関係として追加し、現在の作業ディレクトリがこのモジュール内にある場合に go tool で実行できるようにします。

構文

tool package-path

package-path: ツールのパッケージパス。ツールを含むモジュールと、モジュール内でツールを実装するパッケージへの（場合によっては空の）パスを連結したものです。

例

現在のモジュールで実装されているツールを宣言する
```
module example.com/mymodule

tool example.com/mymodule/cmd/mytool
```

別のモジュールで実装されているツールを宣言する

module example.com/mymodule

tool example.com/atool/cmd/atool

require example.com/atool v1.2.3

注

モジュールで宣言されたツールは、完全修飾パッケージパスで、または曖昧さがない場合は最後のパスセグメントで go tool を使用して実行できます。上記の最初の例では、go tool mytool または go tool example.com/mymodule/cmd/mytool を実行できます。

ワークスペースモードでは、ワークスペースモジュールで宣言されたツールを go tool で実行できます。

ツールは、モジュール自体と同じモジュールグラフを使用してビルドされます。ツールを実装するモジュールのバージョンを選択するには、require ディレクティブが必要です。すべてのreplace ディレクティブまたはexclude ディレクティブも、ツールとその依存関係に適用されます。

詳細については、「ツールの依存関係」を参照してください。

replace

特定のバージョン（またはすべてのバージョン）のモジュールのコンテンツを、別のモジュールバージョンまたはローカルディレクトリに置き換えます。Go ツールは、依存関係を解決する際に置換パスを使用します。

詳細については、「Go モジュールリファレンス」の「replace ディレクティブ」を参照してください。

構文

replace module-path [module-version] => replacement-path [replacement-version]

module-path: 置き換えるモジュールのモジュールパス。
module-version: オプション。置き換える特定のバージョン。このバージョン番号が省略された場合、モジュールのすべてのバージョンが矢印の右側のコンテンツに置き換えられます。
replacement-path: Go が必要なモジュールを探すべきパス。これは、モジュールパスまたは置換モジュールにローカルなファイルシステムのディレクトリへのパスのいずれかです。これがモジュールパスの場合、replacement-version の値を指定する必要があります。これがローカルパスの場合、replacement-version の値は使用できません。
replacement-version: 置換モジュールのバージョン。置換バージョンは、replacement-path がモジュールパスである場合（ローカルディレクトリではない場合）にのみ指定できます。

例

モジュールリポジトリのフォークで置き換える

次の例では、example.com/othermodule の任意のバージョンが、そのコードの指定されたフォークに置き換えられます。
```
require example.com/othermodule v1.2.3

replace example.com/othermodule => example.com/myfork/othermodule v1.2.3-fixed
```
あるモジュールパスを別のモジュールパスに置き換える場合、置き換えるモジュールのパッケージの import ステートメントを変更しないでください。

モジュールコードのフォークされたコピーの使用に関する詳細については、「独自のリポジトリフォークから外部モジュールコードを要求する」を参照してください。
異なるバージョン番号で置き換える

次の例では、モジュールの他のバージョンではなく、バージョン v1.2.3 を使用するように指定しています。
```
require example.com/othermodule v1.2.2

replace example.com/othermodule => example.com/othermodule v1.2.3
```
次の例では、モジュールバージョン v1.2.5 を同じモジュールのバージョン v1.2.3 に置き換えています。
```
replace example.com/othermodule v1.2.5 => example.com/othermodule v1.2.3
```
ローカルコードで置き換える

次の例では、モジュールのすべてのバージョンに対する置換としてローカルディレクトリを使用するように指定しています。
```
require example.com/othermodule v1.2.3

replace example.com/othermodule => ../othermodule
```
次の例では、v1.2.5 のみに対する置換としてローカルディレクトリを使用するように指定しています。
```
require example.com/othermodule v1.2.5

replace example.com/othermodule v1.2.5 => ../othermodule
```
モジュールコードのローカルコピーの使用に関する詳細については、「ローカルディレクトリ内のモジュールコードを要求する」を参照してください。

注

replace ディレクティブは、Go にモジュールのソースを見つけるために別のパスを使用させたい場合に、モジュールパスの値を一時的に別の値に置き換えるために使用します。これにより、Go のモジュール検索は置換先の場所にリダイレクトされます。置換パスを使用するためにパッケージのインポートパスを変更する必要はありません。

exclude および replace ディレクティブは、現在のモジュールをビルドする際のビルド時依存関係解決を制御するために使用します。これらのディレクティブは、現在のモジュールに依存するモジュールでは無視されます。

replace ディレクティブは、次のような状況で役立ちます。

まだリポジトリにない新しいモジュールコードを開発している場合。ローカルバージョンを使用してクライアントとテストしたい場合。
依存関係の問題を特定し、その依存関係のリポジトリをクローンし、ローカルリポジトリで修正をテストしている場合。

replace ディレクティブだけでは、モジュールがモジュールグラフに追加されないことに注意してください。置換されたモジュールバージョンを参照するrequire ディレクティブも、メインモジュールの go.mod ファイルまたは依存関係の go.mod ファイルのいずれかで必要です。置き換える特定のバージョンがない場合は、以下の例のように偽のバージョンを使用できます。ただし、replace ディレクティブはメインモジュールにのみ適用されるため、これはあなたのモジュールに依存するモジュールを壊すことに注意してください。

require example.com/mod v0.0.0-replace

replace example.com/mod v0.0.0-replace => ./mod

Go ツールを使用して変更を行う方法を含む、必要なモジュールの置換に関する詳細については、以下を参照してください。

バージョン番号の詳細については、「モジュールのバージョン番号付け」を参照してください。

exclude

現在のモジュールの依存関係グラフから除外するモジュールまたはモジュールバージョンを指定します。

詳細については、「Go モジュールリファレンス」の「exclude ディレクティブ」を参照してください。

構文

exclude module-path module-version

module-path: 除外するモジュールのモジュールパス。
module-version: 除外する特定のバージョン。

例

example.com/theirmodule バージョン v1.3.0 を除外する
```
exclude example.com/theirmodule v1.3.0
```

注

exclude ディレクティブは、間接的に必要だが何らかの理由でロードできない特定のバージョンのモジュールを除外するために使用します。たとえば、無効なチェックサムを持つモジュールのバージョンを除外するために使用できます。

exclude および replace ディレクティブは、現在のモジュール（ビルドしているメインモジュール）をビルドする際のビルド時依存関係解決を制御するために使用します。これらのディレクティブは、現在のモジュールに依存するモジュールでは無視されます。

go mod edit コマンドを使用してモジュールを除外できます。次の例のようになります。

go mod edit -exclude=example.com/theirmodule@v1.3.0

バージョン番号の詳細については、「モジュールのバージョン番号付け」を参照してください。

retract

go.mod で定義されたモジュールのバージョンまたはバージョンの範囲を依存対象にすべきではないことを示します。retract ディレクティブは、バージョンが時期尚早に公開された場合、またはバージョン公開後に深刻な問題が発見された場合に役立ちます。

詳細については、「Go モジュールリファレンス」の「retract ディレクティブ」を参照してください。

構文

retract version // rationale
retract [version-low,version-high] // rationale

version: 取り消す単一のバージョン。
version-low: 取り消すバージョンの範囲の下限。
version-high: 取り消すバージョンの範囲の上限。version-low と version-high の両方が範囲に含まれます。
rationale: 取り消しを説明するオプションのコメント。ユーザーへのメッセージに表示される場合があります。

例

単一のバージョンを取り消す

retract v1.1.0 // Published accidentally.

バージョンの範囲を取り消す

retract [v1.0.0,v1.0.5] // Build broken on some platforms.

注

retract ディレクティブは、以前のモジュールバージョンを使用すべきではないことを示すために使用します。ユーザーは go get、go mod tidy、またはその他のコマンドで取り消されたバージョンに自動的にアップグレードしません。ユーザーは go list -m -u で取り消されたバージョンを利用可能な更新として認識しません。

取り消されたバージョンは利用可能なままであるべきです。そうすることで、すでにそれらに依存しているユーザーは自分のパッケージをビルドできます。たとえ取り消されたバージョンがソースリポジトリから削除されたとしても、proxy.golang.org などのミラーで利用可能なままになる場合があります。取り消されたバージョンに依存するユーザーは、関連するモジュールで go get または go list -m -u を実行したときに通知される場合があります。

go コマンドは、モジュールの最新バージョンの go.mod ファイル内の retract ディレクティブを読み取ることによって、取り消されたバージョンを発見します。最新バージョンは、優先順位順に次のとおりです。

もしあれば、その最高のリリースバージョン
もしあれば、その最高のプレリリースバージョン
リポジトリのデフォルトブランチの先端の疑似バージョン。

取り消しを追加する際は、通常、新しいより高いバージョンをタグ付けする必要があります。そうすることで、コマンドはモジュールの最新バージョンでそれを見つけることができます。

取り消しを通知することのみを目的としたバージョンを公開することができます。この場合、新しいバージョンはそれ自体も取り消すことがあります。

たとえば、誤って v1.0.0 をタグ付けした場合、次のディレクティブで v1.0.1 をタグ付けできます。

retract v1.0.0 // Published accidentally.
retract v1.0.1 // Contains retraction only.

残念ながら、一度公開されたバージョンは変更できません。後で異なるコミットで v1.0.0 をタグ付けした場合、go コマンドは go.sum またはチェックサムデータベースで不一致のチェックサムを検出する可能性があります。

モジュールの取り消されたバージョンは通常、go list -m -versions の出力には表示されませんが、-retracted を使用して表示できます。詳細については、「Go モジュールリファレンス」の「go list -m」を参照してください。