Go言語のモジュールとパッケージ
2026/07/28

モジュール

モジュールは、1つのアプリやライブラリをまとめる単位です。go.modが置かれたフォルダとその中身全体が1つのモジュールになります。go.modファイルはgo mod initコマンドで生成することができます。サブディレクトリごとにgo mod initする必要はありません。同じgo.modの下にあるパッケージは、すべてこのモジュールに属します。

mkdir demo
cd demo
go mod init example.com/demo
module example.com/demo

go 1.26

go行は、このモジュールが想定するGo言語のバージョンです。

外部パッケージをソースコード上でimportし、go mod tidyコマンドを実行すると、外部ライブラリを自動で検知し、go.modの依存関係を自動で更新してくれます。

パッケージ

パッケージはコンパイルの単位であり、識別子の名前空間でもあります。通常、1つのディレクトリが1つのパッケージです。同じディレクトリの.goファイルには同じpackage句を書き、まとめてコンパイルします。

// greeter/greet.go
package greeter

func Hello(name string) string {
    return "hello, " + name
}
// main.go
package main

import (
    "fmt"

    "example.com/demo/greeter"
)

func main() {
    fmt.Println(greeter.Hello("Go"))
}

import

package句のあと、import宣言で外部から使用したいパッケージを読み込むことができます。

import "fmt"

()を使ってまとめてimportすることもできます。

import (
    "errors"
    myio "io"
    _ "image/png"
)

別名を付けると、パッケージ名の衝突を避けられます。myio "io"ならmyio.Readerのように使います。

importしたパッケージを使用しないとコンパイルエラーになります。使用はしないけどパッケージの初期化だけ実行したいときは_ "image/png"のようにブランクimportします。

import . "fmt"は、パッケージ名なしで識別子を取り込む書き方です。通常ならfmt.Printlnと書くところを、Printlnだけで呼べます。

import . "fmt"

func main() {
    Println("hello") // fmt.Println("hello")と同じ
}

importパスとパッケージ名

importパスは、import "..."に書く文字列です。モジュールパスにディレクトリを足したもので、どのフォルダのコードを取り込むかを指定します。パッケージ名は、取り込んだあとにコード上で使う名前です。そのディレクトリの.goファイル先頭のpackage句で決まります。

// greeter/greet.go
package greeter

func Hello(name string) string {
    return "hello, " + name
}
import "example.com/demo/greeter" // importするときはディレクトリ名

greeter.Hello("Go")               // 呼び出すときはpackage名

公開と非公開

関数や定数といった識別子の公開範囲は、名前の先頭文字で決まります。大文字で始まる名前は他パッケージから参照でき、小文字で始まる名前は同じパッケージ内だけです。

package greeter

func Hello() string { // 他パッケージから呼べる
    return hello()
}

func hello() string { // 同じパッケージ内だけ
    return "hello"
}
import "example.com/demo/greeter"

greeter.Hello()
// greeter.hello() // コンパイルエラー: 小文字は他パッケージから見えない

internalパッケージ

パスにinternalを含むパッケージは、そのinternalの親ディレクトリ以下からだけimportできます。

たとえばexample.com/demo/internal/storeは、example.com/demo/...配下からはimportできますが、別モジュールやexample.com/demoの外にあたるパスからはimportできません。公開したくない実装を内側に閉じるための仕組みです。

ドキュメントコメント

ドキュメントコメントは、トップレベルのpackage、const、var、type、funcの直前に、空行を挟まず書いたコメントです。関数内の変数や、関数の引数・戻り値名には、ドキュメントコメントはありません。

// ParseConfigは設定ファイルを読み込む。
func ParseConfig(path string) (*Config, error) {
    // ...
}

コメントと宣言のあいだに空行があると、ドキュメントにはなりません。

// このコメントはドキュメントにならない

func other() {}

constやvarをまとめたときは、グループ全体へのコメントと、各識別子の行末コメントが使えます。構造体のフィールドとインターフェースのメソッドも、型のドキュメントの一部になります。

// Statusは処理の状態です。
type Status int

const (
    Ready   Status = 1 // 準備完了
    Running Status = 2 // 実行中
)

// Serverは待ち受け設定です。
type Server struct {
    Host string // 待ち受けホスト
    Port int    // 待ち受けポート
}

init関数

パッケージ内にfunc init()を複数定義できます。initはインポートや変数の初期化のあと、自動的に実行されます。

func init() {
    log.SetFlags(log.LstdFlags)
}

パッケージの初期化順序

パッケージの初期化は次の順序です。

  1. インポートされたパッケージ（依存関係の順）
  2. パッケージレベルの変数（宣言順）
  3. init関数（ソースファイル内の出現順）

フォーマット

Go言語のソースコードは、手で細かく揃えるのではなくgofmt（パッケージ単位ならgo fmt）で機械的に整形することができます。インデントはタブ、空白の入れ方や並びも標準形に揃います。

ファイルをその場で書き換える例です。

gofmt -w main.go

パッケージ単位で揃えるときはgo fmtを使います。結果のスタイルはgofmtと同じです。

go fmt ./...

テスト

テストは、対象と同じディレクトリに_test.goで終わるファイルを置きます。書き方は2通りあり、非公開の識別子をテストできるかどうかが異なります。

同じpackage greeterで書くと、非公開の識別子も含めパッケージ内部がすべて見えます。非公開の補助関数や内部状態まで検証したいときに使います。importは不要で、同じパッケージの関数をそのまま呼べます。

// greeter/greet_test.go
package greeter

import "testing"

func TestHello(t *testing.T) {
    if Hello("Go") != "hello, Go" {
        t.Fatal("unexpected greeting")
    }
}

package greeter_testで書くと、他パッケージからの利用と同じです。importが必要で、公開されている識別のみテストできます。

// greeter/greet_ext_test.go
package greeter_test

import (
    "testing"

    "example.com/demo/greeter"
)

func TestHello(t *testing.T) {
    if greeter.Hello("Go") != "hello, Go" {
        t.Fatal("unexpected greeting")
    }
    // greeter.hello() // コンパイルエラー: 他パッケージからは見えない
}

go getで追加し、コードから使う

go getは、指定したモジュールを現在のモジュールの依存として足し、ソースをモジュールキャッシュへ取得します。モジュールキャッシュは、ダウンロードしたモジュールのソースをマシン上に蓄える場所です。既定では$GOPATH/pkg/modにあり、プロジェクトをまたいで再利用されます。プロジェクト直下にライブラリ用のディレクトリは増えません。依存の記録は、プロジェクト直下のgo.modに残ります。

go get rsc.io/quote

go getだけでは、そのパッケージの関数はまだ呼べません。ソースにimportを書き、識別子を使います。

package main

import (
    "fmt"

    "rsc.io/quote"
)

func main() {
    fmt.Println(quote.Hello())
}
go run .

fmtのような標準ライブラリはgo getの対象ではありません。Goのインストールに含まれており、go.modのrequireにも現れません。

go.modとgo.sum

依存を足すと、go.modにrequire行が増えます。使うモジュールとバージョンの記録です。ここに書くバージョンは「このバージョンに固定」ではなく「このバージョン以上」です。自分のgo.modにexample.com/lib v1.2.0とあっても、使っている別モジュールのgo.modに同じモジュールがv1.4.0とあれば、ビルドではv1.4.0が使われます。

module example.com/demo

go 1.26

require rsc.io/quote v1.5.2

あわせてgo.sumができます（または更新されます）。ここには、取得したモジュールバージョンの内容のチェックサムが並びます。次回以降のダウンロードで、同じバージョンの中身が変わっていないかを確かめます。

go.modは「何をどのバージョン以上で使うか」、go.sumは「そのバージョンの中身の指紋」です。役割が違うため、両方をソースと同じバージョン管理に含めます。

requireの行末に// indirectと付くことがあります。メインモジュールのパッケージから直接importされていないモジュールの印です。たとえばrsc.io/quoteを足すと、quoteが使うrsc.io/samplerなどがこの印付きで並ぶことがあります。go getした時点でまだimportしていなければ、そのモジュール自身にも同じ印が付きます。自分のコードへimportを足して直接使うようになれば、この印は外れます。手で付け外しする必要はなく、go getやgo mod tidyが更新します。

go mod tidyと依存のやめ方

もう一つの正規の足し方は、先にソースへimportを書き、あとから依存を揃えることです。

import "rsc.io/quote"
go mod tidy

go mod tidyは、モジュール内のソースがimportしている集合に合わせて、足りないモジュールをgo.modへ足し、どのパッケージからも使われないモジュールを落とします。go.sumも同様に揃えます。

依存をやめるときも、まずソースからそのimportと使用箇所を消し、もう一度go mod tidyを実行します。参照が無ければ、対応するrequireはgo.modから外れます。

バージョンの指定

バージョンを明示するときは、モジュールパスのあとに@とバージョンを付けます。

go get rsc.io/[email protected]
go get rsc.io/quote@latest

@latestは、利用できるなかで最も高いリリースバージョンを選ぶ指定です。リリースバージョンがなければプレリリース、タグがなければリポジトリ既定ブランチ先端のバージョンになります。バージョンを省略したgo get rsc.io/quoteも、取得時点で選ばれた具体的なバージョンがrequireに書かれます。go.modのrequireにlatestという文字列を手で書いてはいけません。バージョンを変えるときはgo getを使います。

メジャーバージョンとimportパス

メジャーバージョンが2以上のモジュールでは、モジュールパスの末尾に/vNが付きます。go getにも、importに書く文字列にも、そのパスを使います。

go get rsc.io/quote/v3@latest
import "rsc.io/quote/v3" // v3のモジュールパス

quote.HelloV3()

import "rsc.io/quote"はv1のモジュールパスです。これではv3のパッケージは使えません。

go getとgo install

現在のモジュールの依存を変えるのがgo getです。揃えるのがgo mod tidyです。

go get rsc.io/quote

一方、バージョン付きで使うgo installは、コマンドを自分の環境へ入れる操作です。実行ファイルは$GOBINがあればそこへ、なければ$GOPATH/binに入り、パスが通っていればその場で呼べます。

go install golang.org/x/tools/cmd/stringer@latest
stringer -help

このプロジェクトのgo.modのrequireは増えません。依存を足したいのにgo installだけ実行すると、プロジェクト側の記録は変わらないままになります。