# Compose Stability: Equal Values Don't Guarantee a Skip

> Compose decides at compile time how to compare each parameter when deciding whether to skip a composable's recomposition, by value if the type proved stable, by reference if it didn't, and that decision is made before any value is ever compared at runtime. The compiler metrics report is the only place that decision is visible, and "my values didn't change" isn't the same question it's answering.

**Date:** 2026-10-31T00:00:00.000Z
**Tags:** Recomposition, Compiler

## What a compiler metrics report actually is

The Compose compiler can optionally write out a report while it compiles
your code. One file lists every composable it saw, annotated with
whether its parameters let it be
skippable (Safe for the compiler to skip re-invoking when its parameters compare equal to last time's.).
Another lists every class, each annotated with the stability the compiler
computed for it: `stable`, `unstable`, or `runtime` when it can't be
resolved until an actual instance shows up.

| Term | Appears on | Means |
|---|---|---|
| `restartable` | composables report | The compiler generated a restart scope for this function at all. Almost every composable gets one; it's the prerequisite for `skippable`, not the interesting part of the line. |
| `skippable` | composables report | This composable's restart scope can short-circuit and skip re-invoking the body when its parameters compare equal to last time's. Missing this keyword means the whole body reruns on every recomposition, no comparison involved. |
| `stable` | both reports | This type's (or parameter's) equality check runs by **value**, `.equals()`. On the classes report it's a property of the type itself; on the composables report it's what a parameter inherited from its type. |
| `unstable` | both reports | The compiler couldn't prove the type is immutable, so the check falls back to **reference** identity, two structurally-equal instances still count as different. |
| `runtime` | classes report only | The type's stability can't be decided from its own definition alone (a generic type parameter, a type from an external module), so the compiler defers the decision to the actual instance at runtime. Never appears as a parameter annotation, only as a class classification. |
| strong skipping mode | build-wide setting | Default since Kotlin 2.0.20. Every restartable composable is `skippable`; stability only decides *how* each parameter gets compared, not *whether* the function can skip at all. |
| classic mode | build-wide setting | The pre-2.0.20 behavior. An unstable parameter cost the whole function its `skippable` keyword, not just that one parameter's comparison. |

* You turn it on with two Gradle properties, `metricsDestination` and
  `reportsDestination`, on the Compose compiler Gradle plugin.
* It's a build artifact, not a runtime tool. No device, emulator, or
  Layout Inspector session needed, the compiler writes it the moment it
  finishes compiling your composables.
* It solves a specific visibility gap: the Layout Inspector can tell you
  a composable recomposed, and how many times, but not *why* it couldn't
  be skipped. The compiler metrics report is the only place that answers
  "why," because it's the compiler's own account of what it decided and
  about which parameter.

## Why this matters for performance

Skipping isn't a bonus Compose occasionally hands you, it's the main lever
it has for keeping recomposition cheap.

* A composable that recomposes reruns its entire body: every nested
  composable call, every `remember` block re-checked, every layout and
  draw node it touches downstream. A skippable composable can
  short-circuit all of that the instant its parameters compare equal; a
  non-skippable one reruns its whole body on every pass regardless of
  whether anything it renders would actually look different.
* The cost doesn't scale with how often *that composable's own data*
  changes, it scales with how often its *parent* recomposes. One
  unstable parameter near the root of a screen is enough to make
  everything beneath it rerun on state changes that have nothing to do
  with it, the single most common cause of a screen feeling janky when
  nothing on it looks like it should be doing much work.

That shows up as three measurable things, and they don't all live in the
same place:

* **Frame duration.** Extra recomposition work adds CPU time inside the
  frame, pushing it past the refresh budget (16.6ms @60Hz, 11.1ms @90Hz).
  Measurable in CI with Macrobenchmark's `FrameTimingMetric`
  (`frameOverrunMs`), and in the field through Android Vitals'
  slow-rendering/frozen-frames data.
* **Jank rate.** `JankStats` classifies a frame as janky once it misses
  that deadline, and it's wired to run in production too: you can log its
  reports to your own analytics from real user sessions, not just local
  runs.
* **Recomposition count.** The odd one out, a local, debug-only
  diagnostic. The Layout Inspector's recompose/skip counters need a
  debuggable or profileable app connected to Android Studio, so they
  never reach a dashboard built from real users. They're what you reach
  for *after* jank rate or frame duration moves in the field and you need
  to reproduce it locally: a composable with a high recompose count and a
  skip count stuck at zero is the exact signature an unstable parameter
  produces.

None of this fails loudly on its own. Nothing crashes, and no lint
warning blocks the build by default.

The composable still produces the right pixels every time you run it.
That's exactly what makes it dangerous:

* **It's invisible at small scale.** Ten items in dev looks identical to
  the stable version in every manual test, and the frame budget above is
  fixed regardless of device, so the margin an unstable parameter eats
  into only shows up once real data and a lower-end device both arrive at
  the same time, which most manual testing never reproduces.
* **It's cheap to introduce, expensive to find later.** By the time it
  shows up in a profiler trace, the fix means tracing the unstable type
  back through every composable and lambda that touched it, not editing
  the one function that looked slow.
* **It invites fixing the wrong thing.** Without checking the compiler
  metrics report, the usual response to a composable that keeps
  recomposing is to add `remember`, hoist state, or split it by guesswork,
  which can quiet the symptom at one call site while the same unstable
  type keeps disabling skipping everywhere else it's used.

That's the practical reason to read the compiler metrics report before
reaching for the Layout Inspector or a system trace first. A
recomposition count or a trace only tells you something recomposed too
often, not *why* it didn't skip.

The report answers that directly. Search it for parameters missing the
`stable` qualifier, or classes marked `unstable`. Whichever one you find
is the actual parameter type responsible.

## The intuition

A composable gets called with the exact same arguments as last time, so it
should skip, right? Not necessarily.

* Compose doesn't decide whether to skip by comparing your actual values at
  runtime first. It decides by checking, at compile time, whether each
  parameter's *type* is one it can compare with `.equals()`, or only by
  reference, with `===`.
* That check happens once, when the compiler reads the type definition. It
  has no idea what instance you'll pass in later, or whether that instance
  ever changes.
* Under strong skipping mode (The mode, default since Kotlin 2.0.20 and the only mode starting Kotlin 2.5.0, where every restartable composable is skippable and the compiler instead chooses how each parameter gets compared when deciding whether a given recomposition can be skipped.), what you're almost certainly running today, that compile-time check no longer decides *whether* a composable can skip. It decides *how* the skip check compares that one parameter.
* A type that fails the check doesn't lose skippability, it loses the right
  to be compared by value. Two calls carrying equal values in two
  different instances of that type still won't skip, only the exact same
  instance does. The values were never the problem, the instance was.

The metrics report is where that decision becomes visible. It doesn't
show you recomposition counts. It shows you the classification the
compiler assigned to every type and every composable, a different
question than what the Layout Inspector answers.

## A list that never changes still isn't guaranteed to skip

```kotlin
// Unstable: plain `List` doesn't guarantee immutability at the type level.
// Some implementation behind that interface could mutate in place without
// Compose ever finding out, so the compiler can't trust an equals() check
// on it. It assumes the worst for every instance of this type.
@Composable
fun MessageList(messages: List<String>) {
    Column {
        messages.forEach { Text(it) }
    }
}
```

The metrics report for this function looks like:

```
restartable skippable fun MessageList(
  messages: List<String>
)
```

Under strong skipping, every restartable composable is `skippable`, so
that keyword alone doesn't change. What's missing is the `stable`
qualifier in front of `messages`. That's the whole story: without it,
Compose compares `messages` by `===` instead of `.equals()` when
deciding whether to skip.

A brand-new `List` built fresh on every recomposition can hold the exact
same three strings as last time. It still fails that check, because it's
a different instance. `===` says no, so the composable reruns.

"My values didn't change" was never the question the compiler was
answering here. "Is this the same instance" was.

```kotlin
// Stable: kotlinx.collections.immutable's ImmutableList is annotated
// @Immutable, so the compiler can trust that once an instance exists, it
// never changes. Two equal instances are provably interchangeable.
@Composable
fun MessageList(messages: ImmutableList<String>) {
    Column {
        messages.forEach { Text(it) }
    }
}
```

```
restartable skippable fun MessageList(
  stable messages: ImmutableList<String>
)
```

Same body, same call sites, same actual data. `messages` earns the
`stable` qualifier this time, and with it, Compose switches the
comparison from `===` to `.equals()`. Now a new instance carrying the
same three strings does skip.

The function was `skippable` both times, the report even says so both
times. The only thing the parameter's type changed is which comparison
gets to decide the skip.

## A lambda's memoization depends on what it closes over

```kotlin
@Composable
fun Toolbar(items: List<String>) {
    // captures `items`; strong skipping memoizes this lambda for you, but
    // the *key* it memoizes by is `items` itself
    val onRefresh = { println("refreshing ${items.size} items") }
    RefreshButton(onClick = onRefresh)
}

@Composable
fun RefreshButton(onClick: () -> Unit) {
    Text("Refresh")
    onClick()
}
```

```
restartable skippable fun Toolbar(
  items: List<String>
)
restartable skippable fun RefreshButton(
  stable onClick: Function0<Unit>
)
```

Both functions report `skippable`, and `onClick` even reports `stable`.
That's because strong skipping memoizes every composable lambda for you,
so the *parameter* itself is always something Compose can rely on. But
that part of the report doesn't tell you anything about `items`.

What `items`' stability actually controls doesn't show up in this report
at all. Behind the scenes, it's the key the compiler uses to decide
whether `onRefresh` gets reused across recompositions of `Toolbar`, or
rebuilt as a new instance. `items` is unstable, so that key is compared
by `===`.

A new `items` list on every recomposition of `Toolbar` means a new key,
whether or not it holds the same three strings. A new key means a new
`onRefresh` every time. `RefreshButton` receives a different `onClick`
instance on every call, so it never skips, even though its own report
line never changes.

```kotlin
@Composable
fun Toolbar(items: ImmutableList<String>) {
    val onRefresh = { println("refreshing ${items.size} items") }
    RefreshButton(onClick = onRefresh)
}
```

```
restartable skippable fun Toolbar(
  stable items: ImmutableList<String>
)
restartable skippable fun RefreshButton(
  stable onClick: Function0<Unit>
)
```

`RefreshButton`'s report line is byte-for-byte identical to the unstable
version, because `RefreshButton` never changed. It still just takes
`() -> Unit`. What changed is `items`' key comparison.

`stable` means `.equals()`, so an equal-content `ImmutableList` now
reuses the same memo key. That reused key means the same `onRefresh`
instance. That's what lets `RefreshButton` skip.

Fixing `items` upstream didn't touch `RefreshButton`'s declaration at all,
the report proves that. It fixed whether `Toolbar` keeps handing
`RefreshButton` the same lambda instance.

> **The fundamental**
>
> This is **stability inference**: purely from a type's own definition,
> the compiler classifies every type a composable's parameters reference
> as stable, unstable, or runtime. Runtime means the type's stability
> depends on something only resolvable later, a type parameter or a type
> from an external module, so the compiler treats it as uncertain until an
> actual instance shows up.
>
> A type is stable when all its public properties are `val`, their types
> are themselves stable, and nothing about the type lets it mutate without
> Compose knowing. That classification is fixed at compile time, once, for
> the type, not a per-instance runtime check.
>
> That's exactly why two structurally-equal instances of an unstable type
> still can't buy you a skip. The compiler disqualified the type before
> either instance existed.
>
> Under strong skipping mode, that disqualification no longer costs the
> composable its `skippable` status. Instead, it costs the parameter its
> `.equals()` comparison: the skip check still runs, just by reference
> instead of by value.

## Elsewhere: same fundamental, different framework

* **React Compiler** (formerly React Forget): analyzes each
  component/hook at build time and decides whether its inputs are safe to
  memoize, inserting the equivalent of `useMemo`/`useCallback`
  automatically. It's the identical question, is this value the kind of
  thing I can trust an equality check on, just answered by a different
  compiler and inspectable in the React Compiler Playground's compiled
  output instead of a metrics file.
* **SwiftUI**: has no compile-time stability report, but reaches the same
  judgment at runtime instead of compile time. A `View`'s body is only
  skipped when its stored properties compare equal (via `Equatable` or
  SwiftUI's own diffing), and `Self._printChanges()` is the debugging tool
  that tells you which property broke that judgment. Same underlying
  question Compose's compiler answers statically, SwiftUI just answers it
  on every frame instead of once at compile time.

## Edge case: classic mode still explains older guides and screenshots

Every report in this post came from strong skipping mode, the default
since Kotlin 2.0.20. If you're reading an older guide, a two-year-old
conference talk, or a teammate's screenshot from before that, it's
showing a report from classic mode. The rules there were different:

* A parameter's type had to be stable before the function could be
  `skippable` at all. An unstable parameter didn't just lose its
  comparison, it disqualified the whole function: no `skippable` keyword,
  full stop.
* The report spelled that disqualification out explicitly, with the word
  `unstable` printed in front of the parameter:
  ```
  restartable fun MessageList(
    unstable messages: List<String>
  )
  ```
* Composable lambdas weren't memoized automatically either, so a lambda
  closing over an unstable capture printed `unstable` too, and the whole
  calling chain downstream lost `skippable` with it.

`unstable messages: List<String>` disqualifying a skip in one report and
only losing a `.equals()` comparison in another isn't a contradiction,
it's two different rule sets answering the same question differently.

Strong skipping can still be turned off per module on Kotlin versions
before 2.5.0, the only way to reproduce a classic-mode report today:

```kotlin
composeCompiler {
    featureFlags = setOf(ComposeFeatureFlag.StrongSkipping.disabled())
}
```

Even that option is on its way out. Enabling it on a current Kotlin
Compose compiler already fails the build with a deprecation error
warning that the flag "should be enabled by default and will be removed
with Kotlin 2.5.0." Check which mode a report came from before trusting a
verdict from an old guide, a teammate's screenshot, or your own notes from
a year ago.

**Skipping isn't a question about whether your values changed. It's a
question about whether the compiler could prove, before your code ever
ran, that checking would be safe.**


---

Canonical page: https://recomposed.blog/compose-compiler-stability-metrics