Skip to content
javahacks.dev
Play Framework

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.

6 min read
Summarize in AI
Flat illustration of a staircase from one version to the next, with the Apache Maven, OpenJDK and Gradle logos.

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.9Play 3.0
Actor and streams libraryAkkaApache Pekko
Licence of that libraryBusiness Source LicenseApache 2.0
Package prefixakka.org.apache.pekko.
Config prefixakka {}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:

java
// 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:

scala
libraryDependencies += "org.apache.pekko" %% "pekko-actor-typed" % "1.1.2"

Configuration keys move as well:

Text
# before
akka.actor.default-dispatcher.fork-join-executor.parallelism-max = 8
# after
pekko.actor.default-dispatcher.fork-join-executor.parallelism-max = 8

A 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.

Shell
# 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.

app/services/ReportActor.javajava
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.

build.sbtscala
// before
libraryDependencies += "com.typesafe.akka" %% "akka-actor-typed" % "2.6.21"

// after
libraryDependencies += "org.apache.pekko" %% "pekko-actor-typed" % "1.1.2"
Shell
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.

DependencyPekko release existsAction
play-slickyes, with Play 3upgrade with Play
akka-persistence-jdbcpekko-persistence-jdbcrename and test recovery
An internal library using akka.actornorebuild it against Pekko first
A vendor SDK shipping Akka shadeddependsask 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.

XML
<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.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.