Play 2.8 to 3 Migration Steps for Your Existing Project
Migrate a Play 2.8 application to Play 3: go through 2.9 first, update sbt and Java, swap Akka for Pekko, fix removed APIs and verify before deploying.

Play 2.8 is two major steps behind. The path is mechanical, and the order keeps each failure explainable. The reasons for the rename are in Play 3 and Pekko.
Step 1: Play 2.8 to 2.9
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.9.6")Also bump sbt.version in project/build.properties to a version the plugin supports, and use Scala 2.13 (Play 2.9 also supports Scala 3). Read the 2.9 migration guide and handle each deprecated item. Typical things:
- Java: some
play.mvchelpers andHttpExecutionContextusage changed. - Guice and dependency injection modules may need updated versions.
- JSON and WS libraries received minor API tidying.
Compile with warnings enabled and fix them while still on Akka, since this keeps the later step small. Run the test suite and deploy this version before continuing if your process allows.
Step 2: Play 2.9 to 3.0
Change the plugin group and version, because the artifacts moved to the org.playframework group:
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.6")The other build changes:
- The Play plugin name changes from
com.typesafe.playtoorg.playframework, and also for modules inlibraryDependenciessuch as"org.playframework" %% "play-json". - Java 11 is the minimum for the sbt plugin, and Java 17 or 21 is the practical choice.
- The
sbt-native-packagerand other plugins need compatible versions.
Step 3: Akka to Pekko
Run a global search for akka and change:
- Java and Scala imports to
org.apache.pekko. application.confkeys underakka { ... }topekko { ... }.- Dependencies from
com.typesafe.akkatoorg.apache.pekko. - Log filters or metrics that match
akkalogger names.
// before
import akka.actor.ActorSystem;
// after
import org.apache.pekko.actor.ActorSystem;A sed-style search and replace over src/ handles most of it, but review the diff, because some strings, like a documentation URL or a type name containing "akka", should stay.
Step 4: check the dependency tree
sbt dependencyTree | grep -i akkaAny hit shows a library still bringing Akka. Replace it with the Pekko version or find an alternative, so only one actor library is on the classpath.
Step 5: verify behaviour
- Start the app and run the full test suite.
- Check configuration overrides in each environment, because a missed
akka.key silently falls back to a default. - Exercise WebSockets, streaming responses, scheduled tasks and anything using actors.
- Compare startup logs between versions for new warnings.
- Deploy to staging and run a load check, with the practices in deploying Play.
Rollback
Keep the 2.9 branch tagged. If a third party library blocks the move, staying on 2.9 for a while is acceptable. Do not mix partial renames, because a half-migrated project has two actor systems.
Find every Akka reference before you start
The size of the migration is the number of places that mention Akka, and a few commands find them all. Run them at the start, keep the output, and run them again at the end; the second run should print nothing.
grep -rn --include='*.scala' --include='*.java' 'akka\.' app test | wc -l
grep -rn --include='*.conf' --include='*.xml' -E '(^|[^a-z])akka([^a-z]|$)' conf | head -20
grep -n 'akka' build.sbt project/*.sbt project/*.properties
sbt "show dependencyTree" 2>/dev/null | grep -i akkaThe first counts source files that import Akka; the second lists configuration keys such as akka.actor.default-dispatcher and logger names; the third finds build coordinates; the fourth lists libraries that pull Akka in transitively. The fourth is the one that decides the schedule, as the Pekko post explains: a library with only an Akka release blocks the move until it publishes a Pekko one or you replace it.
Move through 2.9 before 3.0
The recommended path goes through Play 2.9, which is the last release on Akka and the first with the JDK and Scala level that Play 3 needs. Doing the version change in two steps separates problems: anything that breaks in 2.9 is a Play or Scala change, and anything that breaks in 3.0 is Pekko or the package rename.
// step 1: 2.8 to 2.9 (still Akka)
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.9.x")
// step 2: 2.9 to 3.0 (Pekko). Note the group id changed.
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.x")Replace x with the current patch release from the Play release notes. The group id changed from com.typesafe.play to org.playframework with 3.0, which is an easy line to miss when the build fails to resolve the plugin. Run the full test suite at each step and tag a commit, so that a problem can be bisected between them.
Rename imports mechanically, then read what remains
The import rename is a pattern replacement, and a script is safer than an editor because it covers every file in one pass and can be repeated.
git grep -l 'akka\.' -- '*.scala' '*.java' | xargs perl -pi -e 's/\bakka\.(actor|stream|pattern|util|dispatch|event|japi|routing|testkit)\b/org.apache.pekko.$1/g'
git grep -n 'akka' -- '*.scala' '*.java'The second command prints whatever the pattern did not catch: string literals with class names, akka in logger configuration, and package names outside the list. Each remaining hit needs a decision. Configuration is the second half. In application.conf, the root key akka { ... } becomes pekko { ... }, and the nested keys keep their names, so a block of dispatcher settings moves as a whole.
# before
akka.actor.default-dispatcher.fork-join-executor.parallelism-max = 16
# after
pekko.actor.default-dispatcher.fork-join-executor.parallelism-max = 16A configuration key left under akka is ignored silently, and the actor system runs on defaults, which is a performance regression with no error. After the rename, print the effective configuration at startup in a test and check the values you set are present.
val config = app.configuration.underlying
assert(config.getInt("pekko.actor.default-dispatcher.fork-join-executor.parallelism-max") == 16)Verify behaviour that the compiler cannot see
Three things pass compilation and fail in production. Message serialization for actors that cross nodes or persist events changes its class names, so events written by 2.8 must still be readable; replay a copy of production data on a test environment. Metrics and log filters named after akka stop matching. And libraries that detect Akka on the classpath by class name, such as some monitoring agents, may need a new version. Roll out to a single instance first, compare error rates for a day, and keep the previous release deployable. The rollback is a redeploy of the old version, which works only while the data formats are compatible, so decide before the migration whether you need a window in which both versions run.
Plan the cut-over
Treat the move as two releases. The first release is Play 2.9 with no functional changes, so the team gets used to the new build and the production metrics stay comparable. The second release is Play 3.0 with the Pekko rename. Between them, run the application on 2.9 for at least a full business cycle, such as a month-end for a billing system, to find any problem that depends on the calendar. Before the second release, take a baseline of response time, memory use and error rate on 2.9, and compare it with the same numbers after the move on one instance. A regression in either release has a small search space because only one thing changed.
Communicate the change to the people who operate the application. Dashboards, alerts and log queries that mention akka need updating on the same day, or the first incident after the release will be harder to diagnose than it should be.
Where this does not apply
If you are coming from a version older than 2.8, go through each major step first. Template and routes syntax did not change in this move, see Twirl templates. The reference is the Play 3.0 migration guide, and the Play 2.9 migration guide covers the earlier step.


