To get started with Akka gRPC read the client or server introductions.

Configuring plugin

This plugin is a wrapper for protobuf-gradle-plugin and uses it for .proto files processing and code generation. Most of the settings could be configured using related setting of protobuf-gradle-plugin itself. Consult protobuf-gradle-plugin documentation for details.

The plugin can generate either Java or Scala classes, and then server and or client for the corresponding language. By default both client and server are generated and Java or Scala is autodetected depending on the presence of source files with language extension in src/main.


To add the Akka gRPC gradle plugin to a project:

buildscript {
  repositories {
    maven {
      url ""
plugins {
  id 'java'
  id 'application'
  id 'com.lightbend.akka.grpc.gradle' version '$project.version$'
repositories {
  maven {
    url ""

For a step by step getting started with Akka gRPC read the client or server introductions.

Available plugin options

Following options are available for configuring the plugin code generation. Names and default values are provided.

akkaGrpc {
    generateClient = true
    generateServer = true
    generatePlay = false
    usePlayActions = false
    serverPowerApis = false
    extraGenerators = []

Generating server “power APIs”

To additionally generate server “power APIs” that have access to request metadata, as described here, set the serverPowerApis option:

akkaGrpc {
  serverPowerApis = true

Protoc version

The version and the location of protoc can be changed using protobuf-gradle-plugin settings.

Proto source directory

By default the plugin looks for .proto files under

  • src/main/protobuf
  • src/main/proto
  • app/protobuf
  • app/proto

Loading .proto files from other directories could be configured using settings of protobuf-gradle-plugin.

Loading proto files from artifacts

In gRPC it is common to make the version of the protocol you are supporting explicit by duplicating the proto definitions in your project.

This is supported by protobuf-gradle-plugin and explained here.

Starting your Akka gRPC server from gradle

Build script needs a custom task

task runServer(type: JavaExec) {
  classpath = sourceSets.main.runtimeClasspath
  main = 'com.example.helloworld.GreeterServer'

Then, the server can then be started from the command line with:

./gradlew runServer
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.