Scala 3 Migration Guide

(The Scala Center team is dedicated to providing regular and transparent community updates about project plans & progress. In this forum we created a new topic category to allow quicker orientation going forward: “Scala Center Updates”. Even though all feedback is welcome, we keep the right to make executive decisions about projects we lead. Overview of all our activities can always be found at )

The Scala Center has initiated a migration guide whose purpose is to gather all the information about cross-compiling and upgrading to Scala 3.

Identified Problem

Dotty is the new compiler and improved language that will become Scala 3. Compared to Scala 2, the compiler has been completely redesigned with a new type checker and type inferencer, and a rework of the implicit resolution rules. The language itself has been improved by simplification, restriction and addition of features. The metaprogramming capabilities are being totally rebuilt from the ground.

Those undeniable improvements come at the cost of incompatibilities with Scala 2, which means that a large number of Scala libraries do not compile to Scala 3 and vice versa.

Proposed Solution

The purpose of the migration guide is to provide all information one needs to know before starting cross-compiling its library or upgrading its application. It will eventually contain a tour of the migration tools, a documentation of the automated Dotty rewrite rules, a step by step tutorial for cross-building a library, a step by step tutorial for upgrading an application, and a reference document for migrating macros.

As a complementary effort from the Scala Center, the TASTy Reader project will enable bidirectional dependencies between Scala 2 and 3, allowing separate modules to migrate gradually to the new compiler, rather than all at once. Check out the TASTy Reader roadmap.


The migration guide is a collaborative work. The Dotty team has already joined the effort. Each and every member of the community is encouraged to participate in any of this way:

  • Give your feedback about migrating to Scala 3 in this thread.
  • Help us make the guide more user friendly by opening an issue or, even better, submitting a pull request.
  • Share your knowledge, about the Dotty language and the migration tools.

If you wish to participate but you don’t know where to begin, we encourage you to investigate one of the existing issues.

Scala Center proposed roadmap

May - June 2020

  • Gather feedback about the Dotty community build projects and how they have been migrated.
  • Document the Dotty rewrite rules.
  • Document some incompatibilities that do not have an automated rewrite rule.

July - August 2020

  • Build a step by step guide for cross-compiling a library.
  • Focus on porting the macro-based libraries. Document how one can leverage the new features to avoid macros usage. Document how to cross publish a macro API.

From September 2020

  • Completing and polishing the migration guide.
  • Possibly, porting the migration guide to a website of the Scala ecosystem.
  • Build a step by step guide for upgrading an application to Scala 3.

I just want to say that I’m so, so happy and grateful that the Scala Centre exists. That not a direct response to this one post, but rather this post and all the others, all the projects that it’s taken on and completed. I really feel that the Scala community has levelled-up since Scala Centre’s inception. It would’ve been unfair to Lightbend and EPFL to expect them to cover so much additional scope, even thought it’s all important – tooling & Metals is a great example – and having Scala Centre come in to cover those gaps has been amazing!

So thank you so much for all that you do Scala Centre! Everyone involved has really “completed” the ecosystem (in the movie-esque “you complete me” sense) and it’s night & day now compared to, say, 5 years ago. Huge, huge thanks!


Yes, 天壤之别。

1 Like

Oh, this is such a nice message, I thank you for your work & appreciation!

Truly, all our hard work pays off when we read this. Would you allow me to use (quote you by embedding a screenshot) it for the blog I am writing at the moment about the Scala Center?


Yeah sure, no worries at all! I mean every word of it. :slight_smile:

1 Like

As a test, I tried to port twitter-util to dotty. I ran in to a few issues, some I could work around with more or less ease, some I couldn’t.

  • Much just works.
  • syntax issues were superficial, and easily fixed, commonly through -rewrite
  • java interop issues are tricky. @varargs doesn’t work. @throws doesn’t work. F[Nothing] can’t be cast. For the first one, I could manually write forwarders from java, doing the conversion from Array[A] to Seq[A] manually. I didn’t manage to find workarounds for the last two.
  • Also from Java, I had an issue with type SomeObject$ that I could later no longer reproduce. ¯\_(ツ)_/¯
  • I couldn’t find a way to work with structural types that would cross-compile.
  • One of the dotty issues I ran into was fixed and merged almost as fast as I managed to minimize it
  • A recurring question for various features or implementation details was whether they were still supported but broken, changed or dropped. If I can’t quickly find a feature has been dropped, assuming it’s broken or assuming it’s changed is usually assuming too much, but it’s not always easy to figure out which feature it is that you’re using that’s dropped or changed from the error message. For example: No Manifest available for org.apache.thrift.protocol.TBinaryProtocol.Factory. Manifests have been deprecated since forever. Are they dropped now finally? Or is it an issue with summoning them?

Ah, I ported that to dotty a while ago but then completely forgot to follow-up on the issues I found:

I’m on it:

Yeah we need to do something here, I think import scala.language.reflectiveCalls should be interpreted by dotty to treat structural types the same way scala 2 does.

Dotty doesn’t implement support for Manifest, I think we could but I’d rather let it die finally.


Looks like we came up with similar solutions and workarounds.

I think everyone would rather let it die.


I also just found that @varargs doesn’t work from the Java side. Should I report that as a bug, or is this something that’s a work in progress? I should mention that this is with Version 0.25.0-RC2.

Update: I get the same error message that’s reported in this issue:


FYI: When migrating akka to dotty, I create some scalafix rules such as ConstructorProcedureSyntax, ParensAroundLambda, NullaryOverride,…


Wow this looks great @giabao! Would you be interested in creating a PR in the migration guide to add a link to your repository?


Quick update to say we have documented the Dotty migration rewrites here. Give a try and let us know if you have any comment.