Updating Projects to Newer Editor Versions

A short guide to using the Unreal Engine editor-based project conversion feature

Windows
MacOS
Linux

When a new version of Unreal Engine is released, you have to make a choice about whether to do the work to convert your current project to the new version of the engine, or remain with the engine version you are currently using to maintain the project's functionality as is.

While there is no way to eliminate all the work associated with converting a project, UE4 does offer some assistance. UE4 has a UI-based project update feature that is able to fully update simple projects, and can also offer a head start on the work of updating more complex projects.

For UE4 to convert a project to a later version, you must have Visual Studio 2019 installed.

Converting a Simple Project

If you want to convert a simple project, one that does not yet have complex code or Blueprints, follow the steps below:

  1. Launch the version of UE4 to which you want to convert your project, and find your project; you will notice the UE4 version of each project is listed if it is different from the current version.

    Open existing simple project

  2. Select and open the project. You will be presented with a warning message that the project was made with a different version. By default, UE4 will want to create a copy of the project and convert it to guard against data corruption in the original.

    Convert simple project

    Although we do not recommend either, clicking More Options gives you the choice to open and convert the original project, or to skip converting the project and simply open it as is.

    Convert project more options

    Once you update a project to a newer version of Unreal Engine, you won't be able to open it in an older version. Attempting to do so will fail.

  3. As soon as you click Open a copy (or Convert in-place), UE4 will attempt to automatically generate the code for your project files in the newer version of the engine.

    Generating code progress bar

  4. If UE4 succeeds at the automatic conversion process, your project will open in the editor.

    UE4 project conversion successful

Converting a Complex Project

Converting a complex project is similar to converting a simple one, except that UE4 is unlikely to be able to generate the full code for the project, especially if custom C++ code or Blueprints are used. In such cases, only a partial conversion will be performed, and you will be given the opportunity to finish the conversion process manually in Visual Studio.

For a complex conversion, follow the steps below:

  1. As with a simple project conversion, begin by finding your project. For this example, we are using the deprecated PlatformerGame sample project.

    Open existing complex project

  2. Proceed as described for steps 2–3 of the simple conversion above.

  3. The code generation process for a complex project will usually fail, and generate an error message window containing details about what parts of the conversion process encountered problems.

    Click to expand the image.

  4. You now have the option to open the project in Visual Studio, in order to manually correct the problems that prevented the automatic conversion from completing, which will vary depending on the project's specific details.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss