---
title: protobuf_generate
description: Generate source code with a managed Protobuf compiler.
---

# `protobuf_generate`

`protobuf_generate` runs one built-in `protoc` generator with a managed compiler. It registers generation as a root task and returns its dependency.

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `sources` | Yes | Non-empty list of project-relative `.proto` files. |
| `generator` | Yes | Built-in generator name or a generator returned by [`protobuf_generator`](protobuf_generator.md) or a language package helper. |
| `output` | Yes | Project-relative output directory. |
| `proto_paths` | No | Non-empty list of project-relative import roots. Defaults to `["."]`. |
| `options` | No | Generator option strings, each passed through the matching `--<generator>_opt` flag. Defaults to `[]`. |
| `deps` | No | Dependencies activated before generation, in list order. Defaults to `[]`. |

The selected compiler is implicit; do not add `protoc` to `deps`. xx appends the managed package's bundled include directory after `proto_paths`, so imports such as `google/protobuf/timestamp.proto` resolve without extra configuration. Source files, import roots, and outputs must remain inside the project after symlinks are resolved. Missing output directories are created. Output trees cannot contain symbolic links or overlap another active output.

String generators are limited to `cpp`, `csharp`, `java`, `js`, `kotlin`, `objc`, `php`, `pyi`, `python`, `rbs`, `ruby`, and `rust`. These built-ins vary by Protobuf version. For example, `js` exists only in older releases, while newer generators require newer releases. Unsupported generator/version combinations fail in `protoc`.

Plugin dependencies must be wrapped in a typed generator. Selecting one activates its installation dependency automatically before `protoc`; do not also add it to `deps`. Prefer language-specific helpers such as [`go_protobuf`](../go/go_protobuf.md). `protobuf_generate` contains no language-specific installation behavior.

## Example

```starlark
load("@protobuf@35.1", "protobuf_generate")

protobuf_generate(
    sources=["proto/example/v1/service.proto"],
    generator="python",
    output="generated/python",
    proto_paths=["proto"],
)
```

## Go plugin example

```starlark
load("@go@1.26.5", "go_protobuf")
load("@protobuf@35.1", "protobuf_generate")

protobuf_generate(
    sources=["proto/example/v1/service.proto"],
    generator=go_protobuf("1.36.6"),
    output="generated/go",
    proto_paths=["proto"],
    options=["paths=source_relative"],
)
```

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/examples/zig.md
Title: Zig Examples
Description: Direct Zig commands and Go CGO builds with a managed Zig distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/packages/git/git_clone.md
Title: git_clone
Description: Materialize a pinned Git source tree with host Git configuration and access.

URL: https://withxx.dev/packages/git/git_init_repository.md
Title: git_init_repository
Description: Ensure an empty SHA-1 or SHA-256 Git repository exists.

URL: https://withxx.dev/packages/go/go.md
Title: go
Description: Activate a managed Go SDK for dependent tasks.

URL: https://withxx.dev/packages/go/go_binary.md
Title: go_binary
Description: Build a Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_install.md
Title: go_install
Description: Install a versioned Go command for dependent tasks.

URL: https://withxx.dev/packages/go/go_protobuf.md
Title: go_protobuf
Description: Install protoc-gen-go and provide it as a Protobuf generator.

URL: https://withxx.dev/packages/go/go_run.md
Title: go_run
Description: Run a local program or versioned Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_test.md
Title: go_test
Description: Test Go packages with a managed SDK.

URL: https://withxx.dev/packages/nodejs/nodejs.md
Title: nodejs
Description: Activate managed Node.js for dependent tasks.

URL: https://withxx.dev/packages/nodejs/npm_install.md
Title: npm_install
Description: Install project dependencies with managed npm.

URL: https://withxx.dev/packages/nodejs/npm_run.md
Title: npm_run
Description: Run a project package script with managed npm.

URL: https://withxx.dev/packages/nodejs/npx_run.md
Title: npx_run
Description: Run a versioned npm package command with managed npx.

URL: https://withxx.dev/packages/os/env_append.md
Title: env_append
Description: Append an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_get.md
Title: env_get
Description: Read a value from a task environment while evaluating Starlark.

URL: https://withxx.dev/packages/os/env_prepend.md
Title: env_prepend
Description: Prepend an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_set.md
Title: env_set
Description: Set an environment variable for dependent tasks.

URL: https://withxx.dev/packages/os/env_unset.md
Title: env_unset
Description: Remove an environment variable from dependent tasks.

URL: https://withxx.dev/packages/os/run.md
Title: run
Description: Run a command from the project root.

URL: https://withxx.dev/packages/protobuf/protobuf_generate.md
Title: protobuf_generate
Description: Generate source code with a managed Protobuf compiler.

URL: https://withxx.dev/packages/protobuf/protobuf_generator.md
Title: protobuf_generator
Description: Adapt an installed protoc plugin dependency for code generation.

URL: https://withxx.dev/packages/protobuf/protoc.md
Title: protoc
Description: Activate a managed Protobuf compiler for dependent tasks.

URL: https://withxx.dev/packages/zig/zig.md
Title: zig
Description: Activate managed Zig for dependent tasks.

URL: https://withxx.dev/packages/zig/zig_cc.md
Title: zig_cc
Description: Configure managed Zig as a C and C++ compiler.

URL: https://withxx.dev/packages.md
Title: Built-in Packages
Description: Versioned toolchains, commands, and task environment helpers provided by xx.
-->