参照 - go.modファイルリファレンス（go.mod file reference） - 《Goプログラミング言語

Example
module
go
toolchain
require
replace
exclude
retract

Example

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 Modules Reference の module ディレクティブを参照してください。

Syntax

module module-path

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

Examples

以下の例では、モジュールがダウンロードできるリポジトリドメインの example.com を代入します。

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

Notes

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

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

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

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

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

たとえば、stringtools ディレクトリで開発している場合、一時的なモジュールパスは <company-name>/stringtools になるかもしれません。以下の例では、company-name はあなたの会社の名前です:

go mod init <company-name>/stringtools

go

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

詳細については、Go Modules Reference の go ディレクティブを参照してください。

Syntax

go minimum-go-version

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

Examples

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

Notes

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

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

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 以上では、自動 vendoring が有効になる場合があります。ファイル vendor/modules.txt が存在し、go.mod と一致している場合、-mod=vendor フラグを明示的に使用する必要はありません。
go 1.16 以上では、all パッケージパターンは、main module 内のパッケージとテストによって間接的にインポートされたパッケージのみを一致させます。これは、モジュールが導入されて以来、go mod vendor によって保持されているパッケージの同じセットです。低いバージョンでは、all は、メインモジュール内のパッケージによってインポートされたパッケージのテスト、これらのパッケージのテストなども含まれます。
go 1.17 以上では:
- go.mod ファイルには、メインモジュール内のパッケージまたはテストによって間接的にインポートされたパッケージを提供する各モジュールの明示的な require ディレクティブが含まれます。（go 1.16 以下では、間接依存関係は minimal version selection が他のバージョンを選択する場合にのみ含まれます。）この追加情報は、module graph pruning と lazy module loading を可能にします。
- 以前の 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 ファイルには、最大で 1 つの go ディレクティブを含めることができます。ほとんどのコマンドは、go ディレクティブを現在の Go バージョンで追加します。

toolchain

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

詳細については、Go toolchains および Go Modules Reference の toolchain ディレクティブを参照してください。

Syntax

toolchain toolchain-name

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

Examples

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

Notes

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

require

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

詳細については、Go Modules Reference の require ディレクティブを参照してください。

Syntax

require module-path module-version

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

Examples

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

Notes

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

Go は、replace ディレクティブを使用して、リポジトリ以外の場所からモジュールを要求することができます。

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

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

replace

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

詳細については、Go Modules Reference の replace ディレクティブを参照してください。

Syntax

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

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

Examples

モジュールリポジトリのフォークで置き換え
以下の例では、example.com/othermodule の任意のバージョンが指定されたフォークのコードで置き換えられます。
```
require example.com/othermodule v1.2.3
replace example.com/othermodule => example.com/myfork/othermodule v1.2.3-fixed
```
モジュールパスを別のものに置き換えるときは、置き換えるモジュール内のパッケージのインポート文を変更しないでください。
モジュールコードのフォークを使用する方法については、自分のリポジトリフォークから外部モジュールコードを要求するを参照してください。
異なるバージョン番号で置き換え
以下の例では、バージョン 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
```
モジュールコードのローカルコピーを使用する方法については、ローカルディレクトリにモジュールコードを要求するを参照してください。

Notes

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

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

replace ディレクティブは、次のような状況で便利です:

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

replace ディレクティブ単独では、モジュールを module graph に追加しません。置き換えモジュールバージョンを参照する 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 Modules Reference の exclude ディレクティブを参照してください。

Syntax

exclude module-path module-version

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

Example

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

Notes

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

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

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

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

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

retract

go.mod によって定義されたモジュールのバージョンまたはバージョン範囲が依存されるべきではないことを示します。retract ディレクティブは、バージョンが早期に公開された場合や、公開後に重大な問題が発見された場合に便利です。

詳細については、Go Modules Reference の retract ディレクティブを参照してください。

Syntax

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

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

Example

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

retract v1.1.0 // Published accidentally.

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

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

Notes

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

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

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

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

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

取り消しを示すためだけに公開するバージョンを発行することができます。この場合、新しいバージョンは自分自身を取り消すこともできます。

たとえば、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 または checksum database で不一致の合計を検出する可能性があります。

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