Google Python Style Guide

Getting Your Python Code to Pass Google's Style Checks

The Google Python Style Guide is a set of coding conventions for Python that most enterprise teams adopt alongside or instead of the base PEP 8 standard. It covers naming, formatting, imports, docstrings, and a few quirks that don't appear in the official Python documentation. If you're working in a shop that uses this guide, you will run into its rules whether you like them or not. The guide is available at https://google.github.io/styleguide/pyguide.html, but reading it end to end before you touch it is rarely productive. Most people pick the sections they need as they hit problems. PEP 8 is the default style for Python. Google's version modifies several of its recommendations. The biggest ones affect docstrings, naming of private members, import ordering, and line length. PEP 8 allows docstrings in either double or single quotes. The Google convention mandates double quotes for all docstrings and strings throughout the codebase. It also requires reStructuredText markup inside docstrings instead of plain text, which changes how your documentation tooling parses everything. Private names get two leading underscores under PEP 8, but Google style reserves double underscores for dunder methods only. Everything else gets a single leading underscore with a comment if you need to signal intent. The guide also insists on sorting imports with three blocks: standard library, third-party, and local imports, separated by blank lines. Many linting tools do this automatically now, but if you clone an older codebase, the import order alone can generate hundreds of false positives before you install the right formatter.

Setting Up the Tooling

You can enforce this guide without much pain if you pick the right tools. The core stack I use is pylint with the Google style plugin, yapf for formatting, and black as a secondary option when teams want something opinionated. Run pip install pylint pydocstyle yapf and add a .pylintrc file or pass flags through CI. A typical configuration looks like this: The pylint.extensions.docparams plugin enforces docstring parameter descriptions matching the function signature. Without it, you'll spend more time arguing about whether a docstring is "good enough" than actually writing code. The line length stays at 80 characters because that's what the guide specifies, and fighting it with auto-formatting tools just causes churn. I've seen teams switch to 100 characters to reduce refactor noise, but then they're no longer following the actual guide. About three years ago, I inherited a middleware service written against the Google Python Style Guide that used gRPC-generated code. The generated protobuf stubs used double underscores for methods like Stub.Create patterns that conflicted with Google's own rule about single-underscore privates. Every time we ran pylint, it flagged the generated code as a style violation. The fix was straightforward but tedious: I created a .pylintrc override that disabled specific checks for files under */protos/* and */generated/*, and added a comment at the top of each generated file pointing to the generated source. This cut our CI false-positive count from roughly 400 violations per build down to about twelve real ones. The generated code problem is one of those edge cases nobody warns you about until your pipeline breaks.

Another issue came up with type hints. Google's style guide predates widespread PEP 484 adoption, so its recommendations on generics and type comments are occasionally at odds with modern mypy expectations. When my team started using from __future__ import annotations, pylint complained about syntax it didn't recognize until we upgraded past version 2.12. The workaround was pinning pylint to a version that matched our Python runtime and upgrading mypy independently. The versions diverge more often than people expect, and mismatched tooling creates the kind of subtle breakage that doesn't surface in dev environments.

Docstrings Are Where Most People Fail

The docstring section of the Google Python Style Guide is the hardest part to follow consistently. It requires a specific structure: a one-line summary, a blank line, a detailed description, then parameter and return sections in reStructuredText format. Every function that touches public API needs one. Internal helpers don't strictly need them, but the convention pushes toward uniformity. I've seen teams enforce this across the board, which doubles the boilerplate in large services. The reStructuredText requirement means your docstrings use :param name: and :return: syntax instead of simpler formats. Tools like pydocstyle will flag non-conforming styles immediately. I once spent two days fixing a linting backlog caused by a mix of NumPy-style and Google-style docstrings in the same repo. The solution was picking one format and running a regex-based migration script across the codebase. Mixing styles works technically but destroys tooling consistency and makes code review slower.

Common Pitfalls That Beginners Miss

The first trap is assuming pylint covers everything. It doesn't. Pylint catches naming and basic structure violations but misses formatting details like trailing commas and blank line counts. That's where yapf comes in. Run yapf with the --style google flag before committing, or add it as a pre-commit hook. The second trap is ignoring the constants rule. Google style requires module-level constants to be uppercase with underscores. Variables and class attributes stay camelCase or snake_case depending on context. Confusing these leads to inconsistent APIs and confusing linter output. A third pitfall is the treatment of default mutable arguments. The guide explicitly calls these out and recommends against them, which aligns with general Python best practices. But the specific warning here is about using them in public-facing APIs where the caller might expect state isolation. I've seen bugs where a shared list accumulator caused unexpected behavior across multiple test runs because a developer followed a pattern from a different style guide. Reading the relevant section in the Google Python Style Guide would have prevented that entire class of issue.

When the Guide Doesn't Help

The Google Python Style Guide works well for large teams maintaining monolithic services over years. It doesn't work as well for small scripts, one-off data pipelines, or projects where speed matters more than uniformity. Some rules exist for organizational reasons, not technical ones. The import sorting requirement, for example, has no runtime impact. It exists so code reviews focus on logic instead of formatting debates. In a startup shipping an MVP, that rule is overhead. In a fifteen-person backend team, it's necessary friction. The guide also has no guidance on async patterns, which makes sense given its age. Asynchronous Python code follows different conventions now, and Google's docs don't address them directly. Teams adopting async typically layer FastAPI or asyncio patterns on top of the style guide without formal adaptation. This creates inconsistency in practice. If you're writing async-heavy services, you'll need to supplement the guide with your own conventions around async/await spacing, task naming, and exception handling.

Practical Workflow for Adopting the Style

If you're starting fresh, configure your editor first. VS Code with the Python extension and python.formatting.yapfEnabled set to true handles most of the heavy lifting. Neovim users should look at formatexpr integrations with yapf or black. The goal is zero manual formatting decisions. For existing projects, run yapf over the whole codebase first, then pylint, then fix real issues. Don't fix linting noise from misconfigured plugins. Sort imports using isort with a Google-compatible profile before running any other checks. A complete pre-commit setup I've used successfully looks like this:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-added-large-files
  - repo: https://github.com/google/yapf
    rev: v0.40.2
    hooks:
      - id: yapf
        args: [--style, google, --in-place]
  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort
        args: [--profile, google]
  - repo: https://github.com/pycqa/pylint
    rev: v3.1.0
    hooks:
      - id: pylint
        args: [--rcfile=.pylintrc]

This catches formatting before it hits CI. The cost is roughly three seconds per file on a typical codebase, which is acceptable compared to the ten minutes saved during code review when someone forgets a trailing comma. No style guide is perfect. The Google Python Style Guide's strict 80-character line limit causes excessive wrapping in modern displays where 120 characters is comfortable. The docstring format is rigid and penalizes conciseness. The guide also assumes a Python 3 environment without much consideration for Python 2 legacy code, which still exists in production at several companies. These limitations don't make the guide useless. They make it a set of preferences that work best when paired with reasonable exceptions documented in a team-specific CONTRIBUTING file. The most practical advice I can give is to enforce the rules that affect readability and tooling, and skip the ones that don't. Import order matters for large codebases. Docstring format matters for API documentation. Line length below 100 characters rarely does. Pick your battles, automate the rest, and move on.