Play Framework 3 Pekko Move and What Changes for Apps
What Play Framework 3 changed: Akka replaced by Apache Pekko after the Akka licence change, the package and config renames, and how to plan an upgrade.

In September 2022, Lightbend announced that Akka would move from Apache 2.0 to the Business Source License. Play depends on Akka for its actor system and HTTP server internals, so the Play project had a decision to make. Play 3.0 is its answer: the same framework built on Apache Pekko. This explains what that means for an application.
What Pekko is
Apache Pekko is a fork of Akka 2.6.x, maintained under the Apache Software Foundation and licensed under Apache 2.0. Its API is intentionally close to Akka's, with package names changed. Play 3.0 uses it, and Play 2.9 continues to use Akka under the new licence terms.
| Play 2.9 | Play 3.0 | |
|---|---|---|
| Actor and streams library | Akka | Apache Pekko |
| Licence of that library | Business Source License | Apache 2.0 |
| Package prefix | akka. | org.apache.pekko. |
| Config prefix | akka {} | pekko {} |
The framework's own packages, play.mvc, play.libs, routes and templates, are the same. Controllers and views usually compile as they are.
What changes in code
Imports that mention Akka:
// Play 2.9
import akka.actor.ActorSystem;
import akka.stream.Materializer;
// Play 3.0
import org.apache.pekko.actor.ActorSystem;
import org.apache.pekko.stream.Materializer;Dependency coordinates for libraries that you added yourself change from com.typesafe.akka to org.apache.pekko:
libraryDependencies += "org.apache.pekko" %% "pekko-actor-typed" % "1.1.2"Configuration keys move as well:
# before
akka.actor.default-dispatcher.fork-join-executor.parallelism-max = 8
# after
pekko.actor.default-dispatcher.fork-join-executor.parallelism-max = 8A search for akka across source, conf/ and build files finds nearly all of it. The step-by-step version is in migrating Play 2.8 to 3.
What does not change
Routes, controllers, templates, Ebean or JPA, WS, filters and the testing API are the same. The runtime server is still Netty by default, or Pekko HTTP if you opted in. The build tool is still sbt, see sbt and Play.
Libraries are the real risk
Anything that depends on Akka classes needs a Pekko equivalent or a compatible release: Alpakka becomes Pekko Connectors, Akka HTTP becomes Pekko HTTP, and third party modules may lag. A library that still pulls Akka onto your classpath leaves you with two actor systems, which wastes memory and confuses configuration. Inspect the dependency tree for akka and fix each hit, the way you would for any dependency conflict.
How to choose
- Stay on Play 2.9 if you rely on Akka-only libraries, and your licence situation with the Business Source License is acceptable.
- Move to Play 3 if you want an Apache 2.0 stack with community governance, which most open source and commercial users prefer.
New projects should start on Play 3. For existing ones, plan the upgrade as part of routine maintenance, since Play 2.9 and its Akka line receive security fixes under the new commercial terms for longer-term support only.
Do the rename with a script, then compile
Most of the move is mechanical, and a script makes it repeatable across a repository and reviewable as one commit. Three things change in source: the package prefix, the configuration namespace and the dependency coordinates.
# 1. Java and Scala imports
grep -rl 'akka\.' app test conf | xargs perl -pi -e 's/\bakka\.(actor|stream|pattern|util|dispatch|event|japi|routing)\b/org.apache.pekko.$1/g'
# 2. Configuration keys in application.conf and reference files
perl -pi -e 's/^(\s*)akka(\s*[{.])/${1}pekko${2}/' conf/*.conf
# 3. What remains
grep -rn 'akka' app test conf build.sbt project | grep -v '^Binary'The last command is the real work. It lists everything the patterns did not catch: fully qualified names in strings, logger names such as akka.actor in logback.xml, Kubernetes manifests that set AKKA_ environment variables, and library dependencies. Treat each hit as a question, and expect the list to be short for a plain Play application and long for one that uses clustering or persistence.
A small actor shows the shape of the change. Only the imports differ, and the code that follows them is unchanged.
import org.apache.pekko.actor.AbstractActor;
import org.apache.pekko.actor.Props;
public class ReportActor extends AbstractActor {
public static Props props() { return Props.create(ReportActor.class); }
@Override
public Receive createReceive() {
return receiveBuilder()
.match(String.class, id -> sender().tell("report:" + id, self()))
.build();
}
}Update the build and check the dependency tree
In sbt, Play 3 pulls Pekko in through its own dependencies, and any direct reference to an Akka artifact has to change. Mixing both on the classpath produces two actor systems that cannot talk to each other and, at best, a confusing NoSuchMethodError.
// before
libraryDependencies += "com.typesafe.akka" %% "akka-actor-typed" % "2.6.21"
// after
libraryDependencies += "org.apache.pekko" %% "pekko-actor-typed" % "1.1.2"sbt "dependencyTree" | grep -i -E 'akka|pekko'The command should print Pekko artifacts only. Any com.typesafe.akka line is a library that still depends on Akka transitively, and it is the item to resolve before anything else. Check the Pekko version your Play release expects and do not override it, since Play and its modules are compiled against one specific Pekko line.
Libraries decide the schedule
Application code is the easy part. A Play application depends on libraries built against Akka: the Alpakka connectors, Lagom components, persistence plugins and a number of third-party Play modules. Each one needs a release for Pekko, or a replacement. Make a table before starting.
| Dependency | Pekko release exists | Action |
|---|---|---|
play-slick | yes, with Play 3 | upgrade with Play |
akka-persistence-jdbc | pekko-persistence-jdbc | rename and test recovery |
An internal library using akka.actor | no | rebuild it against Pekko first |
| A vendor SDK shipping Akka shaded | depends | ask the vendor, or isolate it in a separate service |
An internal library is the item that blocks the schedule, because it must be released for Pekko before any application that uses it can move, and every application that uses it moves at once. Release it first with both coordinates published, if you can, and then migrate the applications one at a time.
Test what an import rename cannot show
A successful compile proves that names resolve, not that behaviour is the same. Three behaviours deserve a test before release. Serialization of messages that cross the network or go to a journal: the serializer class names and binding keys changed with the namespace, and a persisted event written under an Akka serializer must still be readable. The cluster configuration, if you use one: seed nodes, roles and the split-brain resolver are configured under pekko.cluster now. And logging: a logback.xml that sets levels for akka loggers silently stops applying, and your debug output vanishes.
<logger name="org.apache.pekko" level="INFO"/>For an application with persisted data, rehearse the upgrade on a copy of the production journal. Start the new version against it and replay a sample of aggregates, comparing state with the old version. A rename that passes every unit test can still fail to read yesterday's events, and the day you discover that should not be a release day.
Where this does not apply
Applications that never touch Akka classes directly are barely affected, except for the dependency swap. Comparisons with other stacks are in Play versus Spring Boot. The reference is the Play 3.0 migration guide, and Apache Pekko documents the library.


