SBT Settings

Basic Installation

To automatically generate Scala case classes for your messages add ScalaPB's sbt plugin to your project. Create a file named project/plugins.sbt containing the following line (or add the following lines if a file with this name already exists):

addSbtPlugin("com.thesamet" % "sbt-protoc" % "1.0.6")

libraryDependencies += "com.thesamet.scalapb" %% "compilerplugin" % "0.11.21"

Add the following line to your build.sbt:

Compile / PB.targets := Seq(
  scalapb.gen() -> (Compile / sourceManaged).value / "scalapb"
)

Running the compile command in sbt will generate Scala sources from your protos and compile them. If you just want to generate Scala sources for your protocol buffers without compiling them, run protocGenerate.

Additionally, if you need customizations from scalapb/scalapb.proto or anything from google/protobuf/*.proto, add the following to your build.sbt:

libraryDependencies += "com.thesamet.scalapb" %% "scalapb-runtime" % scalapb.compiler.Version.scalapbVersion % "protobuf"

Defaults

The plugin assumes your proto files are under src/main/protobuf, however this is configurable using the Compile / PB.protoSources setting.

By default, sbt-protoc invokes protoc 3.x that is shipped with protoc-jar. If you would like to run a different version of protoc:

PB.protocVersion := "-v3.11.4"

See all available options in sbt-protoc documentation

Java Conversions

To enable Java conversions add the following to your build.sbt:

Compile / PB.targets := Seq(
  PB.gens.java -> (Compile / sourceManaged).value,
  scalapb.gen(javaConversions=true) -> (Compile / sourceManaged).value
)

gRPC

Generating gRPC stubs for services is enabled by default. To disable:

Compile / PB.targets := Seq(
  scalapb.gen(grpc=false) -> (Compile / sourceManaged).value
)

Additional options to the generator

scalapb.gen(
  flatPackage: Boolean = false,
  javaConversions: Boolean = false,
  grpc: Boolean = true,
  singleLineToProtoString: Boolean = false,
  asciiFormatToString: Boolean = false,
  lenses: Boolean = true,
  retainSourceCodeInfo: Boolean = false
)

Option	scalapbc	Description
`flatPackage`	`flat_package`	When set, ScalaPB will not append the protofile base name to the package name.
`javaConversions`	`java_conversions`	Generates in the companion object two functions, `toJavaProto` and `fromJavaProto` that convert between the Scala case class and the Java protobufs. For the generated code to compile, the Java protobuf code need to be also generated or available as a library dependency.
`grpc`	`grpc`	Generates gRPC code for services. Default is `true` in `scalapb.gen`, and need to be explicitly specified in `scalapbc`.
`singleLineToProtoString`	`single_line_to_proto_string`	By default, ScalaPB generates a `toProtoString()` method that renders the message as a multi-line format (using `TextFormat.printToUnicodeString`). If set, ScalaPB generates `toString()` methods that use the single line format.
`asciiFormatToString`	`ascii_format_to_string`	Setting this to true, overrides `toString` to return a standard ASCII representation of the message by calling `toProtoString`.
`lenses`	`no_lenses`	By default, ScalaPB generates lenses for each message for easy updating. If you are not using this feature and would like to reduce code size or compilation time, you can set this to `false` and lenses will not be generated.
`retainSourceCodeInfo`	`retain_source_code_info`	Retain source code information (locations, comments) provided by protoc in the descriptors. Use the `location` accessor to get that information from a descriptor.
`scala3Sources`	`scala3_sources`	If set, generates Scala 3-only syntax, including named `given` definitions and `?` wildcards, supporting `-source:future`. Not compatible with Scala 2, even with `-Xsource:3`. Enable only for Scala 3 when cross-building.

Scala 3 wildcard syntax

Changed in ScalaPB 1.x: scala3Sources = true now generates Scala 3-only sources using named given definitions, given-based lens conversions, and modern control-flow syntax compatible with -source:future. Scala 3.3 remains supported. In ScalaPB 0.11.x, this option also supported Scala 2 with -Xsource:3; that compatibility no longer applies in 1.x. Scala 2 builds should leave scala3Sources set to false.

After upgrading, regenerate your sources. If you import generated contextual instances through a wildcard import, you may need a .given import or an explicit named import instead.

Select the generated syntax based on the project's Scala version:

Compile / PB.targets := Seq(
  scalapb.gen(
    scala3Sources = scalaBinaryVersion.value == "3"
  ) -> (Compile / sourceManaged).value / "scalapb"
)

For a Scala 3-only project, you can also set scala3Sources = true directly. This emits ? wildcards, which are required with underscore kind-projector mode. For the ']' expected, but '<:' found error and instructions on regenerating old sources, see the FAQ.

Basic Installation​

Defaults​

Java Conversions​

gRPC​

Additional options to the generator​

Scala 3 wildcard syntax​