できない.dev

Go「cannot find module providing package」の原因と直し方

cannot find module providing package は、import パスからモジュールを見つけられないと出る。
まず go mod tidy、だめなら GOPRIVATE・replace・パスの綴りを確かめる。

公開: 更新:

症状できない · exit 1
go build ./...
main.go:6:2: no required module provides package github.com/google/uuid; to add it:
	go get github.com/google/uuid

2026-10-07 に golang:1.23(Go 1.23.12) で実際に打って取った出力。検証環境の詳細

要約

Go のモジュール解決は go.mod の require と GOPROXY 経由のダウンロードで成り立つ。
require が無いだけなら go build / go run は no required module provides package …; to add it: go get … を出し、go mod tidy で直る。
cannot find module providing package は、go mod tidy などがモジュールを探しに行って import パスを解決できなかったとき(private repo を取得できない、replace の無いローカルモジュールなど)に出る(Go 1.23 で確認)。
どちらかが出た場合、原因は (1) go.mod に require が無い、(2) GOPROXY 経路で取得できない (private / 認証)、(3) ローカル参照が未設定、(4) import パスのタイポ、のいずれかである。
まず go mod tidy を流し、それでも消えなければ環境変数とパスを順に疑う。

実行例

golang:1.23 では、require の無い go.mod のまま github.com/google/uuid を import した go build が、no required module provides package で終了コード 1 になった。
go mod tidy で依存が入ると、go run . が通った。
import パスを github.com/Google/uuid と大文字にした go mod tidy は、module declares its path as で止まった。
replace の無いローカルモジュール example.com/foo は、404 Not Found を伴う cannot find module providing package になった。
go mod edit -replace で ../foo を指すと、go mod tidy が通って hi が出た。

$ go build ./...
main.go:6:2: no required module provides package github.com/google/uuid; to add it:
	go get github.com/google/uuid
$ echo $?
1
$ go mod tidy
go: finding module for package github.com/google/uuid
go: downloading github.com/google/uuid v1.6.0
go: found github.com/google/uuid in github.com/google/uuid v1.6.0
$ go run .
36
$ go mod tidy
go: finding module for package github.com/Google/uuid
go: downloading github.com/Google/uuid v1.6.0
go: found github.com/Google/uuid in github.com/Google/uuid v1.6.0
go: example.com/app imports
	github.com/Google/uuid: github.com/Google/uuid@v1.6.0: parsing go.mod:
	module declares its path as: github.com/google/uuid
	        but was required as: github.com/Google/uuid
$ go mod tidy
go: finding module for package example.com/foo
go: example.com/app imports
	example.com/foo: cannot find module providing package example.com/foo: unrecognized import path "example.com/foo": reading https://example.com/foo?go-get=1: 404 Not Found
$ go mod edit -replace=example.com/foo=../foo
$ go mod tidy
go: found example.com/foo in example.com/foo v0.0.0-00010101000000-000000000000
$ go run .
hi

— 2026-10-07 時点の出力

検証環境Python 3.11.2 / Git 2.39.5 / Go 1.23.12 / 2026-10-07 検証
検証日
実行環境
golang:1.23 Debian GNU/Linux 12 (bookworm)
バージョン
  • Python 3.11.2
  • Git 2.39.5
  • Go 1.23.12

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. go mod tidy を流す

go mod tidy

go mod tidy(新しいタブで開く) は import 文を解析して不足する require を追加・未使用を削除する。
CI では、Go 1.23 以降の go mod tidy -diff でドリフトを検知できる。
ファイルは書き換えず、差分があれば終了コード 1 で終わる。

2. private リポジトリは GOPRIVATE を設定

GOPROXY のデフォルト proxy.golang.org は private を取得できないので、GOPRIVATE と git の insteadOf を組み合わせる。

go env -w GOPRIVATE="github.com/yourorg/*,gitlab.example.com/*"
git config --global url."git@github.com:".insteadOf "https://github.com/"

GOPRIVATE は GONOPROXY と GONOSUMDB の既定値になるので、通常はこの 1 つで両方の除外が効く。
checksum DB の照合だけを個別に外したければ GONOSUMDB、照合そのものを止めるなら GOSUMDB=off を指定する。

3. ローカルモジュールは replace で上書き

開発中の別モジュールを参照するには replace を使う。

go mod edit -replace=example.com/foo=../foo
go mod tidy

go.mod に replace example.com/foo => ../foo が追記される。

4. import パスを正確に書く

v2 以降のメジャーバージョンは import パスにバージョンが入る (github.com/foo/bar/v2)。
リポジトリ URL とは違うので、go.mod の require 行とコードの import 文を必ず突き合わせる。

よくある原因

  1. 新しい依存を import したが、go mod tidy を流しておらず go.mod に登録されていない(このとき go build が出すのは no required module provides package)。
  2. GOPROXY の経路で取得に失敗している。
    private repo / 社内 GitLab を public proxy 経由で取りに行き、410 / 404 になる。
  3. 同一ワークスペース内の別モジュールを参照したいのに、replace の指定が無い。
  4. import パスにタイポがある。
    大文字小文字が違うか、v2 のサブパスが漏れている。