# Guava Source Code Structure: A Comprehensive Guide to Navigating google/guava

> Explore the Guava source code structure with this guide. Learn about its modular Maven/Gradle layout and package organization for JRE, Android, and test utilities.

- Repository: [Google/guava](https://github.com/google/guava)
- Tags: internals
- Published: 2026-08-10

---

**The Guava source code structure follows a modular Maven/Gradle layout with separate directories for the JRE flavor (`guava/`), Android flavor (`android/`), test utilities (`guava-testlib/`), and integration tests, all organized under `com.google.common` packages.**

Understanding the **Guava source code structure** is essential for contributing to or extending Google's core Java libraries. The `google/guava` repository maintains a clean separation between platform-specific implementations while keeping package names consistent across flavors. This guide walks through the exact directory layout, key source files, and how to locate specific utilities within the codebase.

## Repository Layout Overview

The root of the `google/guava` repository contains several distinct modules designed to support multi-platform deployment and comprehensive testing.

- **`guava/`** — Contains the main JRE-flavor implementation with all core collections, concurrency utilities, hashing, graph APIs, and I/O helpers
- **`android/`** — Houses the Android-compatible flavor that mirrors the same APIs but uses Android-optimized implementations
- **`guava-testlib/`** — Provides helper classes and custom assertions used by Guava's internal test suite (e.g., `EscaperAsserts`)
- **`guava-bom/`** — Maven Bill-of-Materials module that defines version alignment for all Guava artifacts
- **`integration-tests/`** — Build scripts and example projects verifying Guava works with Gradle, Maven, and other ecosystems

Root-level build files include [`pom.xml`](https://github.com/google/guava/blob/main/pom.xml) and `build.gradle` descriptors that assemble these modules into distributable JARs, alongside standard documentation files like [`README.md`](https://github.com/google/guava/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/google/guava/blob/main/CONTRIBUTING.md).

## Core Module Structure (`guava/`)

The primary implementation lives inside `guava/src/` following the standard Maven directory layout. Source files are organized under `guava/src/com/google/common/` with functional subpackages:

```

guava/
 └─ src/
     └─ com/google/common/
         ├─ collect/       ← immutable collections, multimaps, caches
         ├─ hash/          ← hashing functions, Bloom filters, primitives
         ├─ graph/         ← graph library (Graph, ValueGraph, Network)
         ├─ util/concurrent/ ← futures, listening executors, rate limiters
         ├─ io/            ← I/O helpers, ByteSource, CharSource
         ├─ math/          ← numeric utilities (LongMath, DoubleMath)
         └─ …               ← additional utility packages

```

### Collections and Immutable Types

The `collect` package contains Guava's most widely used classes, particularly **immutable collections**. The file [`guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/ImmutableList.java) implements the persistent list interface that returns immutable instances via `ImmutableList.of()`.

Other key files in this package include [`ImmutableMap.java`](https://github.com/google/guava/blob/main/ImmutableMap.java), [`ImmutableSet.java`](https://github.com/google/guava/blob/main/ImmutableSet.java), and `Multimap` implementations, all following the same factory method pattern.

### Hashing Utilities

Located under `guava/src/com/google/common/hash/`, the **hashing** package provides cryptographic and non-cryptographic hash functions. The [`Hashing.java`](https://github.com/google/guava/blob/main/Hashing.java) file serves as the primary factory class, offering static methods for Murmur3, SHA-1, SHA-256, and SipHash algorithms.

### Graph API

The `graph` package (`guava/src/com/google/common/graph/`) implements Guava's graph theory library. **Graph.java** defines the core interface for nodes and edges, while **Graphs.java** provides static utility methods for graph creation, traversal, and analysis. This package supports both directed and undirected graphs, including mutable and immutable implementations.

### Concurrency Utilities

Under `guava/src/com/google/common/util/concurrent/`, you'll find utilities for asynchronous programming. **ListenableFuture** implementations and **Uninterruptibles.java** (helpers for dealing with checked exceptions in concurrent code) reside here. The `Futures` class provides transformation and combination methods for chained asynchronous operations.

### I/O and Math Utilities

The `io` package contains `ByteSource`, `CharSource`, and stream handling utilities in `guava/src/com/google/common/io/`. The `math` package offers `LongMath` and `DoubleMath` for overflow-aware arithmetic operations.

## Android Flavor (`android/`)

Guava maintains a separate **Android-compatible source tree** under `android/guava/src/` that mirrors the package structure of the main JRE module. Files like [`android/guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/android/guava/src/com/google/common/collect/ImmutableList.java) contain Android-optimized implementations that avoid Java 8+ language features incompatible with older Android versions.

Import statements remain identical between flavors (`import com.google.common.collect.ImmutableList`), allowing projects to switch dependencies without code changes.

## Testing and Build Infrastructure

### Test Utilities (`guava-testlib/`)

The `guava-testlib` module contains testing helpers used by Guava's own test suite. Classes like `com.google.common.escape.testing.EscaperAsserts` provide specialized assertions for escape/unescape logic. This module is published separately so external projects can use Guava's testing utilities.

### Build Configuration

The root [`pom.xml`](https://github.com/google/guava/blob/main/pom.xml) aggregates all modules using Maven's multi-module structure. For Gradle users, `build.gradle` files in submodules handle compilation. The [`guava/src/module-info.java`](https://github.com/google/guava/blob/main/guava/src/module-info.java) file defines the Java 9 module descriptor, explicitly exporting packages like `com.google.common.collect` and `com.google.common.hash`.

## Practical Code Examples

Below are runnable examples using classes from the core `guava/` module. These work identically in both JRE and Android flavors.

Creating an immutable list:

```java
import com.google.common.collect.ImmutableList;

ImmutableList<String> colors = ImmutableList.of("red", "green", "blue");
System.out.println(colors);   // [red, green, blue]

```

Computing a SHA-256 hash:

```java
import com.google.common.hash.Hashing;
import com.google.common.base.Charsets;

String data = "Guava rocks!";
String hash = Hashing.sha256()
                    .hashString(data, Charsets.UTF_8)
                    .toString();
System.out.println(hash);

```

Building a directed graph:

```java
import com.google.common.graph.GraphBuilder;
import com.google.common.graph.MutableGraph;

MutableGraph<String> graph = GraphBuilder.directed().build();
graph.putEdge("A", "B");
graph.putEdge("B", "C");
System.out.println(graph.successors("A")); // [B]

```

## Summary

- The `guava/` directory contains the standard JRE implementation with packages under `com.google.common` for collections, hashing, graphs, and concurrency
- The `android/` directory mirrors the same structure with Android-compatible implementations at `android/guava/src/`
- Key entry points include [`ImmutableList.java`](https://github.com/google/guava/blob/main/ImmutableList.java) for collections, [`Hashing.java`](https://github.com/google/guava/blob/main/Hashing.java) for cryptography, and [`Graph.java`](https://github.com/google/guava/blob/main/Graph.java) for graph processing
- `guava-testlib/` provides testing utilities, while `guava-bom/` manages dependency versions
- The repository uses Maven multi-module structure with [`pom.xml`](https://github.com/google/guava/blob/main/pom.xml) at the root and module descriptors in subdirectories

## Frequently Asked Questions

### Where is the ImmutableList source code in Guava?

The **ImmutableList** implementation resides at [`guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/ImmutableList.java) in the JRE flavor and [`android/guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/android/guava/src/com/google/common/collect/ImmutableList.java) for Android. Both files implement the same `com.google.common.collect.ImmutableList` public API using platform-appropriate internal mechanisms.

### How does Guava organize its Android-specific code?

Guava maintains a parallel source tree under the `android/` directory that duplicates the package structure of the main `guava/` module. This allows the Android flavor to use optimized implementations (avoiding Java 8 streams, for example) while maintaining identical public APIs and import statements.

### What is the purpose of the guava-testlib module?

The `guava-testlib` module contains testing utilities and custom assertions used by Guava's internal test suite, such as `EscaperAsserts` for testing character escaping logic. It is published as a separate artifact so developers writing extensions to Guava can utilize the same testing infrastructure.

### How do I navigate to the graph API implementation files?

The graph API source files are located under `guava/src/com/google/common/graph/`. Start with [`Graph.java`](https://github.com/google/guava/blob/main/Graph.java) for the core interface definition, then examine [`Graphs.java`](https://github.com/google/guava/blob/main/Graphs.java) for static utility methods. The Android equivalents exist at `android/guava/src/com/google/common/graph/` with identical public interfaces.