2.4. Open edX Birch Release

This section describes how to install the Open edX Birch release.


Now that the Open edX Cypress release is available, edX no longer supports the Birch release.

2.4.1. What’s Included in Birch

The Open edX Birch release contains several new features for students, course teams, and developers. See the Open edX Release Notes for more details.


There are several new features in the Birch release that are available, but not configured in new installations. For details, see the following topics.

2.4.2. What is the Birch Git Tag?

The Git tag for the Birch release is named-release/birch.2. You use this tag to identify the version of Open edX code that is the Birch release.

The following Open edX Git repositories have the Git tag named-release/birch.2:

  • edx-platform
  • configuration
  • cs_comments_service
  • notifier
  • edx-certificates
  • xqueue
  • edx-documentation
  • edx-ora2
  • XBlock

2.4.3. Installing the Birch Release

You can install the Open edX Birch release using Devstack or Fullstack.

Review the prerequisites and instructions for each option, then choose the option that best meets your needs. Ensure you install the required software to run the edX Platform.

If you are upgrading from the Aspen release, see Upgrading from Aspen to Birch.

For new installations, follow the steps below.

  1. Download the Vagrant Box or Download the BitTorrent File.


    The Vagrant boxes have a large file size (about 2.5GB). If you have a slow or unreliable Internet connection, use BitTorrent to download the Vagrant box you need.

  2. Set the OPENEDX_RELEASE Environment Variable.

  3. Install the Vagrant Box. Download the Vagrant Box

If you have a fast and reliable Internet connection, you can download the Vagrant box directly or by running vagrant up when installing Devstack or Fullstack.

See the Open edX Releases Wiki page to access the latest Vagrant boxes.

See Vagrant’s documentation on boxes for more information. Download the BitTorrent File

You can also download the BitTorrent file for the option you selected. BitTorrent is recommended if you have a slow or unreliable data connection. You then use the BitTorrent file to download the Vagrant box. If the Internet connection is temporarily lost while you are downloading the Vagrant box through BitTorrent, you can later continue the download without data loss or corruption.

See the Open edX Releases Wiki page to access the latest Vagrant boxes.

See BitTorrent for more information.

If you download the Vagrant box through BitTorrent, you must add the box to Vagrant before continuing with the installation process.

  • For devstack installations, run the following command.

    $ vagrant box add /path-to-downloaded-box/vagrant-images-birch-2-devstack.box --name birch-devstack-2
  • For fullstack installations, run the following command.

    $ vagrant box add /path-to-downloaded-box/vagrant-images-birch-2-fullstack.box --name birch-fullstack-2 Set the OPENEDX_RELEASE Environment Variable

Before installing the Vagrant box, you must set the value of the OPENEDX_RELEASE environment variable to the Git tag for the Birch release:

export OPENEDX_RELEASE="named-release/birch.2" Install the Vagrant Box

When you have completed the previous steps, install the Birch release by following the installation instructions for Devstack or Fullstack.

2.4.4. Upgrading from Aspen to Birch

You can upgrade your Open edX instance that is running the Aspen release to the Birch release, using the migrate.sh script in the configuration repository, available here.


The upgrade scripts provided are verified only for upgrading instances running the Aspen release. If you are running any other version of the Open edX Platform, the upgrade scripts might not work.


Before upgrading your Open edX instance, back up all data and configuration files. Then verify that you can restore your Open edX instance from the backup files.

On the computer or virtual machine running the Aspen release of Open edX, run the upgrade script for your type of installation:

  • For devstack, run ./migrate.sh -t named-release/birch.2 -c devstack.
  • For fullstack, run ./migrate.sh -t named-release/birch.2 -c fullstack.
  • You can also run ./migrate.sh -h to see which other options the script accepts.

The script creates a temporary directory in which it upgrades Open edX, then cleans up extra files and directories when it finishes running.

After upgrading Open edX to the Birch release, run the edX Platform and verify that course content and data was migrated correctly.