# Guava @Beta APIs: What They Are and When It's Safe to Use Them

> Understand Guava @Beta APIs. Learn what they are and discover when it's safe to use these potentially changing features in your Java projects to avoid breaking changes.

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

---

**Guava `@Beta` APIs are public classes, methods, and fields marked with the `@Beta` annotation that are explicitly excluded from the library's binary-compatibility guarantees and may undergo breaking changes or removal in future releases.**

The Google Guava library uses the `@Beta` annotation to designate experimental features that are not yet frozen in the public API surface. When consuming `google/guava`, understanding these markings is essential, as they signal which components require version pinning and extra scrutiny during dependency upgrades.

## What Are Guava @Beta APIs?

The `@Beta` annotation—defined in [`guava/src/com/google/common/annotations/Beta.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/annotations/Beta.java)—serves as a **contractual signal** between the Guava team and downstream consumers. According to the source code's Javadoc, it "signifies that a public API (public class, method or field) is subject to incompatible changes, or even removal, in a future release."

### Technical Implementation Details

In the [`Beta.java`](https://github.com/google/guava/blob/main/Beta.java) source file, the annotation is configured with specific retention and targeting policies:

- **Retention Policy**: `@Retention(RetentionPolicy.CLASS)` ensures the annotation is stored in the class file but is **not visible at runtime**. This design imposes zero runtime overhead while allowing static analysis tools to detect beta usage via bytecode inspection.
- **Scope**: The annotation supports `ElementType.TYPE`, `ElementType.CONSTRUCTOR`, `ElementType.FIELD`, and `ElementType.METHOD`, meaning entire classes (like `RateLimiter`) or individual methods (like `BigDecimalMath.toBigInteger`) can be independently marked.
- **Propagation**: Guava's documentation pipeline automatically propagates the `@Beta` marker to generated Javadoc pages, ensuring developers see the warning labels when browsing the API reference.

Because beta APIs are excluded from Guava's frozen public surface, they bypass the strict compatibility tests that run against release branches. This allows the Guava team to iterate quickly on new functionality without maintaining backward compatibility for experimental features.

## When Is It Safe to Use @Beta APIs?

The safety of depending on `@Beta` APIs depends entirely on your project's role in the dependency chain and your capacity to manage breaking changes.

**Application Code** — **Safe with caveats**. Applications control their own classpath and Guava version, making it generally safe to use beta APIs. However, you must be prepared to refactor code when upgrading Guava versions, as beta methods may change signatures or disappear entirely.

**Published Libraries** — **Discouraged**. Libraries that appear on users' classpaths should avoid `@Beta` APIs unless absolutely essential. Downstream applications lose control over the Guava version when transitive dependencies conflict, forcing breaking upgrades without their consent.

**Prototypes and Experiments** — **Ideal use case**. Beta APIs are designed for rapid iteration. Using `RateLimiter` or `BigDecimalMath` in proof-of-concept code allows you to leverage cutting-edge utilities without waiting for API stabilization.

**Production Systems with Strict SLAs** — **Avoid unless pinned**. While many production systems successfully use long-standing beta APIs (such as `RateLimiter`, which has carried the annotation since Guava 13.0), you should only do so with a **strictly pinned Guava version** and a documented migration plan.

## Practical Examples of @Beta APIs

Several widely-used Guava utilities remain in beta status. The following examples demonstrate typical usage while acknowledging the contractual risk.

### Rate Limiter Example

The `RateLimiter` class in [`guava/src/com/google/common/util/concurrent/RateLimiter.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/util/concurrent/RateLimiter.java) has been marked `@Beta` since Guava 13.0, yet remains widely adopted for throttling task execution:

```java
import com.google.common.util.concurrent.RateLimiter;

public class ThrottledExecutor {
  // Creates a rate limiter with 5 permits per second
  private static final RateLimiter limiter = RateLimiter.create(5.0);

  public static void submit(Runnable task) {
    // acquire() blocks until a permit is available
    limiter.acquire();
    new Thread(task).start();
  }
}

```

### BigDecimal Math Utilities

The `BigDecimalMath` class in [`guava/src/com/google/common/math/BigDecimalMath.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/math/BigDecimalMath.java) contains precision arithmetic helpers that carry the beta annotation:

```java
import com.google.common.math.BigDecimalMath;
import java.math.BigDecimal;
import java.math.BigInteger;

public class SafeConversion {
  public static BigInteger toBigInt(String value) {
    // Limit integer part to 100 digits to avoid resource exhaustion
    BigDecimal bd = new BigDecimal(value);
    return BigDecimalMath.toBigInteger(bd, 100);
  }
}

```

Both examples rely on APIs that may evolve or relocate in future Guava releases, requiring vigilance when upgrading dependencies.

## Summary

- **@Beta annotation** — Defined in [`Beta.java`](https://github.com/google/guava/blob/main/Beta.java), it marks APIs excluded from binary-compatibility guarantees with `RetentionPolicy.CLASS` to avoid runtime overhead.
- **Application safety** — Safe for applications that control their own Guava version, provided you monitor release notes for breaking changes.
- **Library risk** — Generally inadvisable for published libraries due to transitive dependency conflicts outside your control.
- **Version pinning** — Essential when using beta APIs in production; lock your dependency version and plan for migration.
- **Common examples** — `RateLimiter.create()` and `BigDecimalMath.toBigInteger()` demonstrate real-world beta API usage that requires upgrade awareness.

## Frequently Asked Questions

### Will @Beta APIs be removed without warning?

According to the `google/guava` source code, beta APIs may undergo incompatible changes or removal in future releases. While the team typically provides migration paths for heavily-used beta features (like `RateLimiter`), there is no guarantee of a deprecation period. You should treat `@Beta` as a warning that the API contract is unstable.

### Can I use @Beta APIs in a published library if I shade Guava?

Shading Guava—relocating its packages into your own namespace—mitigates some risk by isolating your specific Guava version from downstream consumers. However, it increases your artifact size and does not eliminate the need to maintain the beta API code yourself if Guava removes it in a future version. The [`Beta.java`](https://github.com/google/guava/blob/main/Beta.java) documentation explicitly discourages library usage regardless of shading.

### How do I detect @Beta API usage in my codebase?

Since `@Beta` uses `RetentionPolicy.CLASS`, it is preserved in compiled bytecode but not available via runtime reflection. You can use static analysis tools like Error Prone or the Guava Beta Checker to scan your source code for `@Beta` annotations. These tools parse the class files or source to flag usage of `com.google.common.annotations.Beta` marked elements.

### Do @Beta annotations affect runtime performance?

No. Because the annotation is defined with `@Retention(RetentionPolicy.CLASS)` in [`Beta.java`](https://github.com/google/guava/blob/main/Beta.java), the JVM discards it after loading the class. It imposes no memory overhead or reflection cost at runtime, serving purely as a compile-time and documentation marker for API stability contracts.