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.


Follow instructions at Gradle plugin portal to apply plugin.

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.

JDK 8 support

If you want to use TLS-based negotiation on JDK 8, Akka gRPC requires JDK 8 update 252 or later. JVM support for ALPN has been backported to JDK 8u252 which is now widely available. Support for using the Jetty ALPN agent has been dropped in Akka HTTP 10.2.0, and therefore is not supported by Akka gRPC.

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.