protolint

protolint is the pluggable linting/fixing utility for Protocol Buffer files (proto2+proto3):

Runs fast because this works without compiler.
Easy to follow the official style guide. The rules and the style guide correspond to each other exactly.
- Fixer automatically fixes all the possible official style guide violations.
Allows to disable rules with a comment in a Protocol Buffer file.
- It is useful for projects which must keep API compatibility while enforce the style guide as much as possible.
- Some rules can be automatically disabled by inserting comments to the spotted violations.
Loads plugins to contain your custom lint rules.
Undergone testing for all rules.
Many integration supports.
- protoc plugin
- Editor integration
- GitHub Action
- CI Integration

Demo

Once MCP server configured, you can ask any MCP clients like Claude Desktop to lint and fix your Protocol Buffer files like this:

Also, vim-protolint works like the following.

MCP Server

protolint now includes support for the Model Context Protocol (MCP), which allows AI models to interact with protolint directly.

Usage

protolint --mcp

For detailed documentation on how to use and integrate protolint's MCP server functionality, see the MCP documentation.

Installation

Via Homebrew

protolint can be installed for Mac or Linux using Homebrew via the yoheimuta/protolint tap.

brew tap yoheimuta/protolint
brew install protolint

Since homebrew-core includes protolint, you can also install it by just brew install protolint. This is the default tap that is installed by default. It's easier, but not maintained by the same author. To keep it updated, I recommend you run brew tap yoheimuta/protolint first.

Via GitHub Releases

You can also download a pre-built binary from this release page:

https://github.com/yoheimuta/protolint/releases

In the downloads section of each release, you can find pre-built binaries in .tar.gz packages.

Use the maintained Docker image

protolint ships a Docker image yoheimuta/protolint that allows you to use protolint as part of your Docker workflow.

❯❯❯ docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto
[_example/proto/invalidFileName.proto:1:1] File name should be lower_snake_case.proto.
[_example/proto/issue_88/oneof_options.proto:11:5] Found an incorrect indentation style "    ". "  " is correct.
[_example/proto/issue_88/oneof_options.proto:12:5] Found an incorrect indentation style "    ". "  " is correct.

From Source

The binary can be installed from source if Go is available. However, I recommend using one of the pre-built binaries instead because it doesn't include the version info.

go install github.com/yoheimuta/protolint/cmd/protolint@latest

Within JavaScript / TypeScript

You can use protolint using your nodejs package manager like npm or yarn.

$ npm install protolint --save-dev

This will add a reference to a development dependency to your local package.json.

During install, the postinstall.js script will be called. It will download the matching protolint from github. Just like @electron/get, you can bypass the download using the following environment variables:

| Environment Variable | Default value | Description | |-------------------------------|---------------------------------------|-----------------------------------------------| | PROTOLINT_MIRROR_HOST | https://github.com | HTTP/Web server base url hosting the binaries | | PROTOLINT_MIRROR_REMOTE_PATH | yoheimuta/protolint/releases/download | Path to the archives on the remote host | | PROTOLINT_MIRROR_USERNAME | | HTTP Basic auth user name | | PROTOLINT_MIRROR_PASSWORD | | HTTP Basic auth password | | PROTOLINT_PROXY | | HTTP(S) Proxy with optional auth data |

Within the remote path, the archives from the releases page must be mirrored.

After that, you can use npx protolint (with all supplied protolint arguments) within your dev-scripts.

{
  ...
  "scripts": {
    "protoc": "....",
    "preprotoc": "npx protolint"
  },
  ...
}

You can add a protolint node to your package.json which may contain the content of protolint.yml below the lint node, i.e. the root element of the configuration will be protolint.

If you want to get an output that matches the TSC compiler, use reporter tsc.

Within Python projects

You can use protolint as a linter within your python projects, the wheel protolint-bin on pypi contains the pre-compiled binaries for various platforms. Just add the desired version to your pyproject.toml or requirements.txt.

The wheels downloaded will contain the compiled go binaries for protolint and protoc-gen-protolint. Your platform must be compatible with the supported binary platforms.

You can add the linter configuration to the tools.protolint package in pyproject.toml.

Usage

protolint lint example.proto example2.proto # file mode, specify multiple specific files
protolint lint .                            # directory mode, search for all .proto files recursively
protolint .                                 # same as "protolint lint ."
protolint lint -config_path=path/to/your_protolint.yaml . # use path/to/your_protolint.yaml
protolint lint -config_dir_path=path/to .   # search path/to for .protolint.yaml
protolint lint -fix .                       # automatically fix some of the problems reported by some rules
protolint lint -fix -auto_disable=next .    # this is preferable when you want to fix problems while maintaining the compatibility. Automatically fix some problems and insert disable comments to the other problems. The available values are next and this.
protolint lint -auto_disable=next .         # automatically insert disable comments to the other problems. 
protolint lint -v .                         # with verbose output to investigate the parsing error
protolint lint -no-error-on-unmatched-pattern . # exits with success code even if no file is found (file & directory mode)
protolint lint -reporter junit .            # output results in JUnit XML format
protolint lint -output_file=path/to/out.txt # output results to path/to/out.txt
protolint lint -plugin ./my_custom_rule1 -plugin ./my_custom_rule2 .   # run custom lint rules.
protolint list                              # list all current lint rules being used
protolint version                           # print protolint version
protolint --version                         # print protolint version (global flag)
protolint -v                                # print protolint version (when used as the only argument)

protolint does not require configuration by default, for the majority of projects it should work out of the box.

Version Control Integration

protolint is available as a pre-commit hook. Add this to your .pre-commit-config.yaml in your repository to run protolint with Go:

repos:
  - repo: https://github.com/yoheimuta/protolint
    rev: v0.56.3 # Select a release here
    hooks:
      - id: protolint

For Docker-based execution, use the protolint-docker hook:

repos:
  - repo: https://github.com/yoheimuta/protolint
    hooks:
      - id: protolint-docker # Uses yoheimuta/protolint:latest by default

Important: For Docker hooks, the rev parameter is meaningless for versioning per pre-commit's design. To pin to a specific protolint version, specify the Docker image tag in the entry:

repos:
  - repo: https://github.com/yoheimuta/protolint
    hooks:
      - id: protolint-docker
        entry: yoheimuta/protolint:v0.55.6 lint # Pin to specific version