The protobuf Gradle plugin adds proto alongside java

Two jobs, and the second one has a catch

The README describes the plugin's job as two steps. First, it assembles the Protobuf Compiler command line and uses it to generate Java source files from your proto files. Second, it adds those generated files to the input of the corresponding Java compilation unit, the sourceSet in a Java project and the variant in an Android project, so they compile alongside your Java sources.

The catch is stated immediately after. If you are generating non-Java or Kotlin source files, they will not be included for compilation automatically, and you need to add them to sources for language-specific compilations. That is the single most important limitation for anyone using this plugin as a generic protobuf build tool rather than as a Java code generator.

Applying the plugin takes one block, and the version is the only thing you must get right:

plugins {
  id "com.google.protobuf" version "0.10.0"
}

Version 0.10.0 is the latest release and requires at least Gradle 7.6 and Java 11. The plugin must work with either the Java plugin or the Android plugin, which is the only constraint it states on the host build.

A proto source directory per sourceSet, compiled in one protoc run

The plugin's mental model is that proto files are organised the way Java sources are. It adds a sources block named proto next to java on every sourceSet, and by default it includes all *.proto files under src/$sourceSetName/proto.

The rule that follows from that is worth knowing: the proto files of one sourceSet, or one variant in an Android project, are compiled in a single protoc run, and the generated files are added to the Java compilation run of that same sourceSet or variant.

Customising the directory works the way java sources are customised. For a Java project you use the top-level sourceSet block and add directories alongside the default:

sourceSets {
  main {
    proto {
      // In addition to the default 'src/main/proto'
      srcDir 'src/main/protobuf'
      srcDir 'src/main/protocolbuffers'
      // In addition to the default '**/*.proto' (use with caution).
      // Using an extension other than 'proto' is NOT recommended,
      // because when proto files are published along with class files, we can
      // only tell the type of a file from its extension.
      include '**/*.protodevel'
    }
  }
}

That comment about extensions is the useful warning in the block. When proto files are published next to class files, the type of a file is inferred from its extension, so including a different extension works locally and can break downstream consumers.

For an Android project the same proto block goes under android.sourceSets, mirroring the java block.

protoc comes from Maven, not from your PATH

By default the plugin searches for the protoc executable in the system search path, and the README recommends against relying on that by pointing you at pre-compiled protoc binaries published on Maven Central:

protobuf {
  ...
  // Configure the protoc executable
  protoc {
    // Download from repositories
    artifact = 'com.google.protobuf:protoc:3.0.0'
  }
  ...
}

A local path is the alternative:

protobuf {
  ...
  protoc {
    path = '/usr/local/bin/protoc'
  }
  ...
}

Multiple assignments are allowed in the protoc block and the last one wins, which is a small trap when you merge build files: a stray path assignment silently overrides an artifact.

Codegen plugins work the same way. A plugin named foo is looked up as protoc-gen-foo on the system path unless you declare it in the plugins block, where grpc is given as the example and both an artifact and a local path are shown. Declaring a plugin does not run it: the README is explicit that you must configure the tasks in the generateProtoTasks block to apply the plugins defined in plugins.

The artifact syntax follows Gradle's artifact classifier rules, where the default classifier is project.osdetector.classifier and the default extension is exe. A non-C++ codegen plugin can be used with a constant classifier such as "com.example:example-generator:1.0.0:-jvm8_32".

Tasks must be configured in generateProtoTasks, and the names are not an API

The plugin generates one task per protoc run, which corresponds to a sourceSet in a Java project and to a variant in an Android project. Each task has configuration interfaces controlling the type of outputs, the codegen plugins to use and parameters.

The rule is stated as a requirement rather than a suggestion: you must configure these tasks in the generateProtoTasks block. That block provides helper functions to reach the tasks tied to a particular build element and also ensures your configuration is picked up correctly by the plugin. Configuring tasks outside that block is listed under a DONOTs heading together with the instruction not to assume task names, because they may change.

That is a stability contract worth taking seriously. It is the plugin telling you that its task names are an implementation detail, which is different from most Gradle plugins and easier to work around if you know it in advance: put every task-specific setting inside generateProtoTasks and avoid depending on task names.

Configuration overall is split across three blocks, which is the layout most first-time users trip over. sourceSets or android.sourceSets control where proto files live, the protobuf block locates the protoc executable and the codegen plugins, and generateProtoTasks configures what each run produces.

Examples, test projects and a custom licence

Two runnable examples ship with the plugin. The Groovy example is the default and is tested by running ../../gradlew build from the example directory. The Kotlin DSL example is labelled experimental, is tested with ./gradlew build, and is set up with Gradle 4.10, which the README names as the minimum required version for that example.

The bulk of the configuration surface is exercised by directories whose names start with testProject, and there are a lot of them: testProjectLite, testProjectBase, testProjectCustomProtoDir, testProjectBuildTimeProto, testProjectConfigureJavaExecutable, testProjectDependent, testProjectJavaAndKotlin, testProjectKotlin, and the Android variants including testProjectAndroidBare, testProjectAndroidBase, testProjectAndroidBase9, testProjectAndroidLibrary, testProjectAndroidKotlin and testProjectAndroidKotlinDsl. Those directories serve as usage examples for advanced options but cannot be compiled as individual projects, so reading them is the only way to see an advanced option in context.

Trying the head version means building it locally: download the source and run ./gradlew publishToMavenLocal -x test, with tests skipped because they require the Android SDK. Then add mavenLocal() alongside gradlePluginPortal() in the pluginManagement repositories block in settings.gradle, and reference version 0.10.1-SNAPSHOT in the plugins block.

The last push was on 2026-09-29 and the most recent releases are v0.10.0 on 2026-04-20, v0.9.6 on 2025-12-17 and v0.9.5 on 2025-03-31. The licence is a custom one that GitHub cannot classify, so read the LICENSE file rather than assuming Apache-2.0 or MIT.

Editorial conclusion

The protobuf Gradle plugin is the right tool for a Java or Android project that keeps .proto files under src/main/proto and wants protoc resolved from Maven rather than from whatever is on the PATH. It is the wrong tool when you generate Kotlin, Go or other language sources, because the README states those outputs are not added to any compilation automatically. Before upgrading, read the release notes: the README opens by warning that usage or compatibility requirements may change between versions.

Frequently asked questions

Official sources

1. google/protobuf-gradle-plugin on GitHub
2. Issues
3. README
4. Releases