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

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

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

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

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

$ go mod init example/mymodule

依存関係を管理するには、goコマンドを使用します。これらのコマンドは、go.mod ファイルに記述されている要件が常に整合性を保ち、go.mod ファイルの内容が有効であることを保証します。これらのコマンドには、go get、go mod tidy、go mod editコマンドなどがあります。

goコマンドのリファレンスについては、コマンド goを参照してください。コマンドラインでgo help *コマンド名*と入力すると（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ディレクトリで開発している場合、一時的なモジュールパスは<company-name>/stringtoolsになる可能性があります。次の例では、company-nameは会社の社名です。

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.sumファイルのgo.modファイルのチェックサムをより慎重に保持するようになりました。

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

toolchain

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

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

構文

toolchain toolchain-name

toolchain-name: 推奨されるGoツールチェーンの名前。標準的なツールチェーン名は、Goバージョン`V`に対して`goV`という形式を取ります（例：`go1.21.0`、`go1.18rc1`）。特別な値`default`は、自動的なツールチェーンの切り替えを無効にします。

例

Go 1.21.0以降の使用を推奨します。
```
toolchain go1.21.0
```

備考

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

godebug

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

構文

godebug debug-key=debug-value

debug-key: 適用する設定の名前。設定の一覧とそれらが導入されたバージョンは、[GODEBUG履歴](https://go.dokyumento.jp/doc/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）またはGoによって生成された擬似バージョン番号（例：v0.0.0-20200921210052-fa0125251cc4）のいずれかになります。

例

リリースバージョン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に要求させることができます。

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

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

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
```
1つのモジュールパスを別のモジュールパスで置き換える場合、置き換えるモジュールのパッケージのインポート文は変更しないでください。

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

次の例は、モジュールの他のバージョンではなく、バージョン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`を参照してください。