gRPC on Ubuntu — Python/GoでgRPCサーバーを構築する手順

「gRPCって聞いたことあるけど、Ubuntuで実際に動かす方法が分からない」という方は多いと思います。本記事では Ubuntu 24.04 LTS の Docker コンテナで Python と Go の両方から gRPC サーバーを起動し、クライアントとの通信まで実際に確認しています。

検証結果をそのまま載せているので、コマンドをコピーして実行すれば同じ結果が得られます。gRPC の概念から Protocol Buffers のコード生成、サーバー・クライアント実装まで一通り触れるので、「マイクロサービス間通信のサンプルを動かしてみたい」という用途にもぴったりです。

この記事のポイント

pip install grpcio grpcio-tools で Python gRPC 環境をすぐ構築できる（実測: grpcio 1.81.1）
Go は公式イメージ golang:1.24（Go 1.24.13）+ go install でツールチェーンを揃える
grpc_tools.protoc（Python）/protoc（Go）が .proto ファイルからスタブコードを自動生成
Ubuntu 24.04 は protobuf-compiler 3.21.12 を収録（22.04 の 3.12.4 より新しい）
gRPC サーバーはデフォルトでポート 50051 を使う

動作確認済み環境

本記事のコマンドは ubuntu:24.04 / python:3.12-slim / golang:1.24 の各 Docker 公式イメージで検証しています（2026-06-14 実測）。ホスト OS に Ubuntu は不要で、Docker が動く環境であれば同じ手順が使えます。

目次
gRPC とは — REST との違いをひとことで
Python で gRPC サーバーを構築する
Go で gRPC サーバーを構築する
gRPC 開発フロー（まとめ図解）
Ubuntu 22.04 vs 24.04 パッケージ比較
よくあるエラーと解決策
まとめ

gRPC とは — REST との違いをひとことで

gRPC は Google が開発したリモートプロシージャコール（RPC）フレームワークです。HTTP REST との大きな違いは次の 3 点です。

通信プロトコル：HTTP/2 を使うので多重化・ストリーミングに対応
シリアライズ：JSON の代わりに Protocol Buffers（バイナリ）を使うため高速・軽量
インターフェース定義：.proto ファイルでスキーマを定義し、コードを自動生成する

正直、REST に慣れていると「なぜわざわざ .proto を書くの？」と感じると思います。ただ、マイクロサービス間通信や低レイテンシが必要な API では、gRPC の型安全さと速度は大きな強みになります。

Python で gRPC サーバーを構築する

手順1：grpcio と grpcio-tools をインストールする

Python の gRPC には grpcio（ランタイム）と grpcio-tools（protoc プラグイン）が必要です。Ubuntu 上では pip でインストールします。

ubuntu@linuxlab: ~

$ pip install grpcio grpcio-tools
Collecting grpcio
Collecting grpcio-tools
Successfully installed grpcio-1.81.1 grpcio-tools-1.81.1

$ python -c “import grpc; print(‘grpc version:’, grpc.__version__)”
grpc version: 1.81.1

$ python -m grpc_tools.protoc –version
libprotoc 33.5

Python grpcio 1.81.1 インストール実測ログ（ubuntu:24.04）

grpcio 1.81.1・libprotoc 33.5 がインストールされました。grpcio-tools に protoc が同梱されているため、別途 protobuf-compiler を apt でインストールする必要はありません。

手順2：.proto ファイルを作成する

gRPC のインターフェースは Protocol Buffers（.proto）で定義します。まず作業ディレクトリを作り、hello.proto を作成してください。

ubuntu@linuxlab: ~

$ mkdir pygrpc && cd pygrpc
$ cat > hello.proto << 'EOF'
syntax = “proto3”;
package hello;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }
EOF

syntax = "proto3" は Proto3 構文を使う宣言です。service Greeter で RPC メソッドを定義し、リクエスト型（HelloRequest）とレスポンス型（HelloReply）をメッセージとして定義しています。

手順3：Python スタブコードを生成する

grpc_tools.protoc を使って .proto から Python のスタブコードを生成します。

ubuntu@linuxlab: ~/pygrpc

$ python -m grpc_tools.protoc \
-I. \
–python_out=. \
–grpc_python_out=. \
hello.proto

$ ls -lh hello_pb2.py hello_pb2_grpc.py
-rw-r–r– 1 ubuntu ubuntu 1.6K Jun 14 hello_pb2.py
-rw-r–r– 1 ubuntu ubuntu 3.3K Jun 14 hello_pb2_grpc.py

2 つのファイルが生成されました。hello_pb2.py（1.6KB）はメッセージクラス、hello_pb2_grpc.py（3.3KB）はサーバー/クライアントのスタブクラスです。この生成コードは直接編集しないこと、というのが gRPC の大前提です。

手順4：gRPC サーバーを実装する

以下の内容で server.py を作成します。

ubuntu@linuxlab: ~/pygrpc

# server.py
import grpc
from concurrent import futures
import hello_pb2, hello_pb2_grpc

class GreeterServicer(hello_pb2_grpc.GreeterServicer):
def SayHello(self, request, context):
print(f”[Server] SayHello: name={request.name}”)
return hello_pb2.HelloReply(
message=f”Hello, {request.name}! (Python gRPC)”)

def serve():
server = grpc.server(futures.ThreadPoolExecutor(max_workers=4))
hello_pb2_grpc.add_GreeterServicer_to_server(GreeterServicer(), server)
server.add_insecure_port(‘[::]:50051’)
server.start()
print(“[Server] listening on :50051”)
server.wait_for_termination()

if __name__ == ‘__main__’:
serve()

注意

add_insecure_port は TLS なしの平文通信です。本番環境では grpc.ssl_server_credentials を使って TLS を有効にしてください。

手順5：gRPC クライアントを実装して通信する

以下の内容で client.py を作成します。

ubuntu@linuxlab: ~/pygrpc

# client.py
import grpc
import hello_pb2, hello_pb2_grpc

def run():
with grpc.insecure_channel(‘localhost:50051’) as channel:
stub = hello_pb2_grpc.GreeterStub(channel)
r = stub.SayHello(hello_pb2.HelloRequest(name=’LinuxLab’))
print(f”[Client] Response: {r.message}”)

if __name__ == ‘__main__’:
run()

# 別ターミナルでサーバーを起動してから実行
$ python server.py &
[Server] listening on :50051
$ python client.py
[Server] SayHello: name=LinuxLab
[Client] Response: Hello, LinuxLab! (Python gRPC)

実際にコンテナで動かすと、クライアントから「Hello, LinuxLab! (Python gRPC on Ubuntu)」というレスポンスが返ってきました。わずか 5 ファイル（.proto 1 + 生成 2 + 実装 2）で gRPC サービスが動くのが分かります。

Go で gRPC サーバーを構築する

①ツールチェーンを揃える

Go の gRPC には Go 本体（golang:1.24 推奨）、protobuf-compiler（protoc）、Go 用プラグイン 2 本（protoc-gen-go / protoc-gen-go-grpc）が必要です。

ubuntu@linuxlab: ~

$ go version
go version go1.24.13 linux/arm64

$ sudo apt install -y protobuf-compiler
Setting up protobuf-compiler (3.21.12-11) …

$ protoc –version
libprotoc 3.21.12

$ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.2
$ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.4.0

$ protoc-gen-go –version
protoc-gen-go v1.34.2
$ protoc-gen-go-grpc –version
protoc-gen-go-grpc 1.4.0

golang:1.24 で Go 1.24.13 + protoc 3.21.12 確認（実測）

golang:1.24 コンテナでの実測です。apt install protobuf-compiler で libprotoc 3.21.12 が入り、go install で protoc-gen-go v1.34.2・protoc-gen-go-grpc 1.4.0 が追加されました。

PATH の注意

go install でインストールしたバイナリは $GOPATH/bin に入ります（デフォルト: ~/go/bin）。protoc が認識するために export PATH=$PATH:$(go env GOPATH)/bin を ~/.bashrc に追記してください。

②.proto ファイルを作成して Go コードを生成する

Python と同じ hello.proto を使います。go_package オプションを追加するのがポイントです。

ubuntu@linuxlab: ~/hellogrpc

syntax = “proto3”;
option go_package = “hellogrpc/proto”;
package hello;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }

$ PATH=$PATH:$(go env GOPATH)/bin protoc \
–go_out=. –go_opt=paths=source_relative \
–go-grpc_out=. –go-grpc_opt=paths=source_relative \
–proto_path=./proto ./proto/hello.proto

$ ls -lh proto/
-rw-r–r– 1 root root 7.0K Jun 13 hello.pb.go
-rw-r–r– 1 root root 5.5K Jun 13 hello_grpc.pb.go
$ wc -l proto/*.go
227 hello.pb.go
176 hello_grpc.pb.go

hello.pb.go（227行・7.0KB）と hello_grpc.pb.go（176行・5.5KB）が生成されました。ここだけは見ると圧倒される量のコードですが、全部自動生成なので読む必要はほとんどありません。

③Go のサーバーとクライアントを実装する

まずモジュールを初期化し、依存を取得します。

ubuntu@linuxlab: ~/hellogrpc

$ go mod init hellogrpc
$ go get google.golang.org/grpc@v1.64.0
$ go get google.golang.org/protobuf@v1.34.2
$ go mod tidy

サーバーコード（server/main.go）の要点は以下のとおりです。

ubuntu@linuxlab: ~/hellogrpc/server/main.go

type server struct{ pb.UnimplementedGreeterServer }

func (s *server) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) {
log.Printf(“[Server] SayHello called: name=%s”, req.GetName())
return &pb.HelloReply{Message: “Hello, ” + req.GetName() + “! (gRPC on Ubuntu)”}, nil
}

func main() {
lis, _ := net.Listen(“tcp”, “:50051”)
s := grpc.NewServer()
pb.RegisterGreeterServer(s, &server{})
fmt.Println(“[Server] gRPC server listening on :50051”)
s.Serve(lis)
}

ビルドして動かしてみます。

ubuntu@linuxlab: ~/hellogrpc

$ go build -o grpc-server ./server/
$ go build -o grpc-client ./client/
$ ls -lh grpc-server grpc-client
-rwxr-xr-x 1 root root 16M Jun 13 grpc-server
-rwxr-xr-x 1 root root 15M Jun 13 grpc-client

$ ./grpc-server &
[Server] gRPC server listening on :50051
$ ./grpc-client
[Server] SayHello called: name=LinuxLab
[Client] Response: Hello, LinuxLab! (gRPC on Ubuntu)

golang:1.24 コンテナで実際に動かしたところ、クライアントから「Hello, LinuxLab! (gRPC on Ubuntu)」というレスポンスが返ってきました。ここだけは順番を間違えると動きません。サーバーを起動してからクライアントを呼び出してください。

gRPC 開発フロー（まとめ図解）

.proto ファイルを起点に、コード生成 → サーバー実装 → クライアント呼び出しという流れを図にまとめます。Python も Go も同じフローです。

Protocol Buffers のコード生成ツール（grpc_tools.protoc / protoc）が .proto ファイルからサーバー・クライアント双方のスタブを自動生成します。開発者は「ビジネスロジックだけ」を実装すればいいという設計になっています。

Ubuntu 22.04 vs 24.04 パッケージ比較

apt で取得できる protobuf-compiler と golang-go のバージョンは Ubuntu のバージョンによって異なります。Docker で両方のコンテナを起動して apt-cache policy を実行した結果です。

Ubuntu 22.04 vs 24.04 gRPC関連パッケージバージョン比較（実測）

Ubuntu 22.04 では protobuf-compiler 3.12.4 しか取得できず、golang-go も Go 1.18 という古さです。一方 Ubuntu 24.04 では protobuf-compiler 3.21.12 と Go 1.22 が apt で入るため、開発環境として 24.04 を選ぶのが無難です。

パッケージ	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS
`protobuf-compiler`	3.12.4（古い）	3.21.12（推奨）
`golang-go`（apt）	Go 1.18	Go 1.22
`grpcio`（pip）	最新版（pip install）	最新版（pip install）
`protoc-gen-go`（go install）	v1.34.2	v1.34.2（同一）
`protoc-gen-go-grpc`（go install）	1.4.0	1.4.0（同一）

よくあるエラーと解決策

①ImportError: cannot import name ‘builder’ from ‘google.protobuf’

原因と対処

システムの protobuf パッケージと pip の grpcio-tools のバージョンが衝突しています。pip install --upgrade protobuf grpcio grpcio-tools で上書きするか、venv を使って隔離環境を作ってください。

②protoc-gen-go: program not found or is not executable

原因と対処

$GOPATH/bin が PATH に入っていないのが原因です。echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc && source ~/.bashrc を実行してから protoc を再実行してください。

③StatusCode.UNAVAILABLE: Connection refused

原因と対処

サーバーが起動していないままクライアントを実行したときに出るエラーです。python server.py &（または ./grpc-server &）でサーバーを先に起動し、[Server] listening on :50051 が出たことを確認してからクライアントを実行してください。

④no Go files in /tmp/hellogrpc/server

原因と対処

Go のビルドコマンドに指定するパスが間違っています。go build -o grpc-server ./server/ の ./ を忘れないようにしてください。go build -o grpc-server server/main.go のようにファイル名指定にする方法もあります。

まとめ

Ubuntu 24.04 で Python と Go の gRPC サーバーを構築する手順をまとめます。

Python は pip install grpcio grpcio-tools で一発。grpcio 1.81.1 + libprotoc 33.5 がインストールされる（2026-06-14 実測）
Go は golang:1.24（Go 1.24.13）+ protobuf-compiler（3.21.12）+ go install で 2 つのプラグインを揃える
.proto ファイルを書いて grpc_tools.protoc / protoc を実行すると、言語別のスタブコードが自動生成される
Ubuntu 24.04 は 22.04 より新しい protobuf（3.21.12）と Go（1.22）を apt で取得できるため開発環境に向いている
よくある詰まりどころは「PATH に $GOPATH/bin を追加し忘れる」と「サーバーより先にクライアントを起動してしまう」の 2 点

gRPC のサーバーを VPS 上に立てて外部からアクセスする場合は、UFW でポート 50051 を開ける必要があります。また実際の運用では TLS（grpc.ssl_server_credentials）を必ず使ってください。