ProcessPhoenix: restarting an Android process instead of faking it

A restart tool for state changes a configuration change cannot express

The README is two sentences long, and the second one is the important constraint. Process Phoenix facilitates restarting your application process, and this should only be used for things like fundamental state changes in your debug builds, for example changing from staging to production.

That second sentence is doing real work, because it rules out the use most people would reach for first. A configuration change, a rotation, a locale switch, a theme toggle: Android already has a lifecycle mechanism for those, and reaching past it would mean holding state in memory across a change the platform intended to handle. What ProcessPhoenix is for is the case where the app's assumptions about its own environment have become wrong at runtime and no amount of recreation will help, because the values were read once into singletons, into a database layer, into a network client.

The mechanism is the platform's own, not a trick. The library launches your application into a new process, which means the old process goes away and every static field, every cached singleton and every long-lived client is discarded along with it. The next launch reads configuration again, and this time reads the value that has actually changed.

That framing is why the debug-build emphasis is there. In a debug build you control the build, you can change which backend you point at, and being wrong about it is an ordinary thing you want to fix quickly. In a shipped application, silently destroying and recreating the process would discard whatever the user was doing, so the library is telling you not to reach for it there.

The API is one call, and it wants a Context

Starting the default activity in a new process takes a single line:

ProcessPhoenix.triggerRebirth(context);

There is no builder, no options object and no listener. The call takes the application context and returns, having arranged for the process to be replaced.

The overload exists for the case where the new process should start something other than the default activity, and it takes the intent you want used:

Intent nextIntent = //...
ProcessPhoenix.triggerRebirth(context, nextIntent);

The intent is built by you, so the destination screen is your decision rather than the library's. This is the variant you want when restarting for a state change is also a navigation event, for instance coming back into the app on a particular destination after switching environments.

The signature taking a Context rather than an Activity is worth pausing on, because it is what lets the call live in application-scoped code. The library is not tied to a screen. A setting changed from a preference listener, a switch flipped from a widget, a broadcast received by a receiver: all of those have a context, and none of them have an activity they should depend on.

The one guard your onCreate has to add

Restarting a process means your application object and your launcher activity will run again inside it, before anyone has decided whether this launch is a genuine fresh start or a step inside the restart you just requested. The library exposes the check that resolves that:

if (ProcessPhoenix.isPhoenixProcess(this)) {
  return;
}

The README frames it as a way to skip initialization in onCreate when your application is inside the Phoenix process. The early return is the whole contract, and skipping it is the mistake that makes this kind of library feel dangerous.

What goes wrong without it is fairly easy to reason about. Any initialization you do at the top of onCreate, whether it is loading a configuration value, opening a database, registering a network client or kicking off a request, will run once for the dying process and again in the new one. The first run's results are discarded, so you get double work and occasionally a side effect twice. In the new process, the guard is what makes the launch look like the clean start you asked for instead of a second partial initialization on top of one already in progress.

The check is on `this`, so it works in an activity. The README's example places it at the top of onCreate for exactly that reason.

Version 3 moved the class off Activity and added service restarts

There is one release in the project's published history, version 3.0.0, dated 2024-03-25, and its notes list three changes.

New: support restarting services, through a method named `triggerServiceRebirth`. New: restart an activity with only a class reference, rather than requiring you to construct an intent. Changed: the ProcessPhoenix class no longer extends Activity, with the note that in practice no one should have been relying on this anyway.

That last change is the one to notice, because it is a breaking change to an inheritance relationship rather than a signature change, which is the kind that compiles fine and behaves differently. The library no longer being an Activity is consistent with the Context-based API described above, and it means the class can be called from anywhere that has a context.

The service variant matters for anyone whose fundamental state change affects background work rather than a visible screen. A long-running service holding a connection built from the configuration that just changed has the same problem as an activity does, and before 3.0.0 the library offered no way to address it.

The absence of a 2.x release in the published history is worth noting rather than reading into. The repository has a CHANGELOG.md and a RELEASING.md at the root, so the fuller history exists in the repository even where the published release feed does not show it.

One dependency coordinate and a sample module

Installation is a single Gradle dependency, tagged groovy in the README because that is the convention for build scripts:

implementation 'com.jakewharton:process-phoenix:3.0.0'

Snapshots of the development version are available in Sonatype's snapshots repository, which the README links. That is the whole distribution story: no wrappers, no services, no initialization step.

The repository tree confirms how small the project is. There is `process-phoenix/` for the library itself and `sample/` for a usage example, and the sample has its own `build.gradle` and `src/` directory. Alongside those sit `build.gradle`, `settings.gradle`, `gradle.properties`, the Gradle wrapper in both shell and batch forms, plus `CHANGELOG.md`, `RELEASING.md` and `LICENSE.txt`.

A sample module in a library this size is a deliberate choice rather than an accident. The integration has one non-obvious requirement, the onCreate guard, and a sample is the cheapest way to make sure callers place it correctly. If you are evaluating the library, the sample is where the intended call site is demonstrated.

The license is Apache 2.0, with the copyright line naming Jake Wharton and 2015, which tells you the project's origin predates its first published release by several years.

Where the README stops

The documentation is thin by design and it is worth being clear about what that leaves unanswered. The README does not explain how the restart is performed at the platform level, what happens to a process holding pending work, how the new process interacts with the one being replaced, or how the intent variant merges flags and categories with your manifest's launcher intent. Those details are either in the source or nowhere, and for a library this small the source is short enough to read.

It also does not enumerate what is safe to put after the guard. If your onCreate continues past `isPhoenixProcess`, which it must, deciding which parts of your initialization are safe to skip on the second launch is application-specific work the library cannot do for you.

What the README does settle is the decision that matters most: this is for fundamental state changes in debug builds, not for routine lifecycle handling. Once you have accepted that framing, the remaining question is only where in your code the call belongs, and the sample module is there to answer it.

With 2,138 stars, 138 forks and 11 open issues, and a last push on 2026-09-25, the project is small, stable and not looking for new features.

Editorial conclusion

ProcessPhoenix is one of those libraries whose entire design is a single insight: Android will let you tear down and rebuild your process if something actually launches you into a new one, and almost nothing else will do that for you on demand. The API is three calls, the integration cost is one guard in onCreate, and the scope the README states is deliberately narrow, debug builds and fundamental state changes such as moving from staging to production. That narrowness is a strength rather than a limitation, since the library has 2,138 stars and 11 open issues with a last push on 2026-09-25 and no signs of feature drift. If you need a service restarted the same way, version 3.0.0 added `triggerServiceRebirth`. Add the coordinate, call it where a configuration change would genuinely be wrong, and put the process check at the top of onCreate before anything else runs.

Frequently asked questions

Official sources

1. Issues
2. JakeWharton/ProcessPhoenix on GitHub
3. License: Apache-2.0
4. README
5. Releases