Migrating to Swift 5

Xcode 10.2 comes with a Swift Migrator tool that helps you migrate your project to Swift 5.

For the previous release’s Migration Guide, see Migrating to Swift 4.2.

Pre-Migration Preparation

Make sure that the project that you intend to migrate builds successfully in Swift 4 or Swift 4.2 mode, and all its tests pass. You may need to resolve errors initially due to compiler changes.

It’s highly recommended to have your project managed under source control. This will allow you to easily review the changes that were applied via the migration assistant and to discard them and re-try the migration if needed.

You decide when and if you’d like to migrate on a per-target basis when it makes sense for your project. While migrating to Swift 5 is definitely encouraged, it’s not an all-or-nothing process, as Swift 4, 4.2, and 5 targets can coexist and link together.

The migration assistant does a migrator build to gather the changes, using the scheme you have selected, so the targets that will get processed are the ones that are included in the scheme. To review and modify what is included in the scheme, invoke the Edit Scheme… sheet and select the Build tab from the column on the left, and make sure all your targets and their unit tests are included.

If your project depends on other open-source projects that are provided by Carthage or CocoaPods, consult the Using Carthage/CocoaPods Projects section.

Swift Migration Assistant

When you open your project with Xcode 10.2 for the first time, you will see a migration opportunity item in the Issue Navigator: click it to activate a sheet asking you if you’d like to migrate. You can be reminded later or invoke the Migrator manually from the menu Edit -> Convert -> To Current Swift Syntax…

You will be presented with a list of targets to migrate. Targets that do not contain any Swift code will not be selected.

Clicking Next will bring up the Generate Preview sheet and the assistant will initiate a migration build to get source changes. When this is done, you will be presented with all the changes that will be applied once you click on ‘Save’. This will also change the Swift Language Version build setting for the migrated targets to Swift 5.

There may have been issues with processing the targets that will negatively impact the migration process. Switch to the Report Navigator and select the Convert entry that was added; this is the conversion build log. Check the log for errors that may have showed up.

If you see errors about not being able to code-sign the target, try disabling code-signing from the build settings of the target. If you see other errors, please file a bug report and include the details. You are strongly encouraged to attach a project that illustrates the faulty migration if possible.

Swift 5 Migration Changes Overview

Swift 5 has minimal impact to code compiled with 4.2 version. Here’s what you may encounter on your own code:


Swift Standard Library


The source compatibility changes for the SDK between 4.2 and 5 modes are minimal and they were necessary to improve the correctness of the APIs.

Migrating from Swift 4

If you are migrating from Swift 4 code, also see the migration changes overview from last year’s migrator from Migrating to Swift 4.2.

After Migration

While the migrator will take care of many mechanical changes for you, it is possible that you may need to make more manual changes to be able to build the project after applying the migrator changes.

Even if it compiles fine, the code that the migrator provided may not be ideal. Use your best judgement and check that the changes are appropriate for your project.

Using Carthage/CocoaPods Projects

Here are some important points to consider when migrating a project with external dependencies using package managers like the Swift Package Manager, Carthage or CocoaPods.