go mod initは、Goのプロジェクトを「モジュール」として初期化し、go.modファイルを新規に作成するコマンドです。Goで依存パッケージを管理しながら開発を始める際の、最初の一歩にあたる操作です。

この記事の要点
go mod initは、カレントディレクトリをモジュールのルートとしてgo.modを作成するコマンドです。 書式はgo mod init モジュールパスで、モジュールパスにはリポジトリのURL（例：github.com/user/repo）を指定するのが一般的です。 生成されるgo.modには、最低限module行とgo行が書き込まれます。 初期化後はコードを書き、go mod tidyを実行することで、必要な依存パッケージが自動的に解決・記録されます。 モジュールパスは後から変更すると修正範囲が広がりやすいため、最初に決めておくのが無難とされています。

 

go mod initとは

go mod initは、Goのコマンドラインツールに含まれるサブコマンドの一つで、実行したディレクトリを起点とするモジュール（module）を新規に作成します。具体的には、そのディレクトリにgo.modという設定ファイルを生成し、ファイルの先頭にモジュールの名前（モジュールパス）とGoのバージョンを書き込みます。

ここで言うモジュールとは、Goにおける依存関係管理の単位です。一つのgo.modが管理する範囲が一つのモジュールであり、その中に複数のパッケージ（ディレクトリ）を含めることができます。go mod initは、このモジュールの「土台」を用意するコマンドだと考えると分かりやすいでしょう。

初期化が済むと、以降はgo getやgo mod tidyといったコマンドがgo.modを参照・更新しながら、外部パッケージのバージョンを記録・管理してくれるようになります。逆に言えば、go.modがないディレクトリでは、こうしたモジュールベースの依存管理は機能しません。

 

基本的な使い方

基本の書式は次の通りです。プロジェクトのルートにしたいディレクトリへ移動し、モジュールパスを引数に与えて実行します。

go mod init モジュールパス

たとえば、GitHub上のgithub.com/user/repoというリポジトリで開発するプロジェクトであれば、次のように実行します。

mkdir myapp cd myapp go mod init github.com/user/repo

実行に成功すると、おおむね次のようなメッセージが表示され、同じディレクトリにgo.modが作られます（表示内容は環境やバージョンによって異なります）。

go: creating new go.mod: module github.com/user/repo

新しいバージョンのGoでは、引数のモジュールパスを省略してgo mod initだけで実行できる場合もあります。この場合、ディレクトリ名やバージョン管理の情報からモジュールパスが推測されますが、意図しない名前になることもあるため、自分でパスを明示して指定する方法が確実です。

 

生成されるgo.modの中身

go mod init github.com/user/repoを実行した直後のgo.modは、最小限の構成だと次のような内容になります。

module github.com/user/repo   go 1.22

各行が表す主な内容は次の通りです。

記述	役割
moduleディレクティブ	このモジュールのモジュールパスを宣言します。importでパッケージを参照するときの基準にもなります。
goディレクティブ	このモジュールが想定するGoの言語バージョンを示します。多くの場合、初期化時のGoのバージョンが書き込まれます。

この段階ではまだ外部パッケージを使っていないため、依存関係を記録するrequireディレクティブは含まれていないのが一般的です。外部パッケージを使い始めると、require行が追加されていきます。

なお、go.modは手作業でも編集できますが、依存関係に関わる行は基本的にコマンド側が管理します。意図せず整合性が崩れるのを避けるため、依存の追加・削除はコマンド経由で行うのが無難です。

 

初期化のあとの流れ

go mod initはあくまでスタート地点です。実際の開発では、おおよそ次のような流れになります。

手順	操作	内容
1	go mod init	モジュールを初期化し、go.modを作成する。
2	コードを記述	.goファイルを作成し、必要に応じて外部パッケージをimportする。
3	go mod tidy	コードを読み取り、不足している依存をgo.modに追加し、不要な依存を削除する。
4	go build／go run	解決済みの依存を使ってビルド・実行する。

たとえば、外部パッケージをimportしたコードを書いたあとに次のコマンドを実行すると、必要なパッケージが取得され、go.modとgo.sumが更新されます。

go mod tidy

go.sumは、依存パッケージの内容を検証するためのチェックサムを記録するファイルで、go mod tidyやgo getの実行に伴って自動的に作成・更新されます。

 

モジュールパスの命名

モジュールパスは、そのモジュールを一意に識別するための名前です。Goでは慣習として、コードを置くリポジトリのURLをそのままモジュールパスにする方法が広く使われています。

例	想定される用途
github.com/user/repo	GitHub上のリポジトリで公開・共有するプロジェクト。
example.com/internal/tool	独自ドメイン配下で管理する社内向けのツールなど。
example（短い名前）	外部公開を前提としない、学習や動作確認のためのプロジェクト。

リポジトリのURLをモジュールパスにする利点は、他のプロジェクトからそのコードをimportするとき、URLと参照先が一致して取得しやすくなる点にあります。一方で、外部に公開せず手元で動かすだけのプロジェクトであれば、必ずしもURL形式である必要はなく、短い名前でも初期化自体は行えます。ただし、後から公開する可能性があるなら、最初からURL形式にしておくほうが移行の手間が少なくて済みます。

 

go mod tidyとの連携

go mod initとgo mod tidyは、役割が分かれていて補い合う関係にあります。

コマンド	主な役割	実行のタイミング
go mod init	モジュールの作成（go.modの生成）。	プロジェクトの最初に一度だけ。
go mod tidy	依存関係の追加・削除と整理。	importを増減させたあと、繰り返し。

つまり、go mod initは土台を一度だけ用意するコマンド、go mod tidyはその土台の上で依存関係を継続的に整えるコマンド、という役割分担になっています。初期化だけでは依存は記録されないため、外部パッケージを使う場合はgo mod tidy（またはgo get）を組み合わせて使うのが基本的な流れです。

 

落とし穴と注意点

つまずきやすいポイント	内容と対処
モジュールパスの後からの変更	モジュールパスはコード内のimportパスや、他プロジェクトからの参照先と結び付いています。後から変更すると関連する記述の修正が必要になりやすいため、最初に方針を決めておくと手戻りを抑えられます。
既にgo.modがある状態での実行	同じディレクトリにgo.modが既に存在する場合、go mod initはエラーになるのが一般的です。初期化済みのプロジェクトでは、依存の更新にはgo mod tidyやgo getを使います。
GOPATH時代との違い	かつてはGOPATHという特定のディレクトリ配下にコードを置く必要がありましたが、モジュール方式ではgo.modがあれば任意の場所で開発できます。古い解説ではGOPATH前提の手順が混在していることがあるため、情報の前提に注意してください。
実行する場所を間違える	go mod initは実行したディレクトリをモジュールのルートにします。意図しない上位ディレクトリで実行すると範囲がずれるため、プロジェクトのルートに移動してから実行しているか確認しましょう。

 

よくある質問

Q. 引数のモジュールパスは省略できますか？
A. 新しいバージョンのGoでは省略できる場合があり、その際はディレクトリ名やバージョン管理の情報からモジュールパスが推測されます。ただし意図しない名前になることもあるため、自分で明示的に指定するほうが確実です。

Q. go mod initを実行すると外部パッケージも一緒にダウンロードされますか？
A. いいえ。go mod initが行うのはgo.modの作成までです。外部パッケージの取得や記録は、コードにimportを書いたうえでgo mod tidyやgo getを実行したときに行われます。

Q. 一度作ったgo.modを作り直したいときはどうすればよいですか？
A. 既存のgo.modがある状態ではgo mod initは実行できないのが一般的です。やり直したい場合は、内容をよく確認したうえでgo.modを削除してから初期化し直すか、モジュールパスだけを変えたいのであればgo.modのmodule行を直接修正する方法があります。いずれの場合も、変更後はgo mod tidyで整合性を取り直すと安全です。