Last updated February 22, 2016. Created on October 19, 2013.
Edited by pfrenssen, dokumori, Pravin Ajaaz, Log in to edit this page.

  1. Get a copy of Drupal 8

    Development environment

    In order to start your Drupal 8 module upgrade, first set up your development environment. You will need a local web stack (MAMP, LAMP, etc.), git, and a code editor or IDE. See Setting up a test environment for more information.

    Install a Drupal 8 stable release

    Next, install a copy of Drupal 8 to use for testing. We recommend using the most recent stable release of Drupal 8 to work on contributed modules (rather than the nightly development build or git repository.) You can find the latest Drupal 8 stable release on the listing of releases for Drupal 8 core.

  2. Create your 8.x codebase

    Place your module in the /modules folder

    As of Drupal 8.0, most core files are now contained in a core/ subdirectory, so that site builders can now use the top-level modules/ and themes/ folders for contributed and custom extensions. (See the change record on the new core subdirectory.) So, you can place your module's git repository directly inside the modules/ folder.

    Contributed module maintainers: Create an 8.x branch

    • Navigate into your Drupal 8 installation's modules directory.
    • Go to the version control tab on your project page on, and follow the instructions to clone the latest 7.x branch.
    • Create a new 8.x branch from the 7.x branch.
    • Push the new 8.x branch back to

    Example commands

    cd ~/Sites/8.x/modules
    git clone --branch 7.x-prague
    cd pants
    git checkout -b 8.x-1.x
    git push -u origin 8.x-1.x

    Non-maintainers: Create an 8.x sandbox

    Example commands

    mkdir xjm_pants
    cd xjm_pants
    git init
    git remote add origin
    git remote add pants
    git fetch --all
    git checkout -b xjm-8.x-1.x remotes/pants/8.x-1.x
    git push origin xjm-8.x-1.x
  3. Things to keep in mind

    First, just get it working

    When upgrading a module to Drupal 8, your first goal should be to just get it working. Drupal 8 includes many powerful improvements from Drupal 7, and you might want to rework some of the module's code later to match Drupal 8 best practices. But for now, just concentrate on making the module's basic functionality work.

    Change records

    Your most important resource for upgrading modules to Drupal 8 is the 8.x change record list. This listing has documentation for every backwards compatibility break from Drupal 7, including before-and-after code examples for each change. Any time you encounter a problem while working on your module upgrade, your first step should be to search this listing for a relevant keyword.

    Help us make Drupal 8 better!

    Need help?

    If you can't find the answer to a question you encounter when working on your module upgrade, join IRC and ask other Drupal contributors for help! Many Drupal developers and contributed module maintainers participate in the #drupal-contribute, so if you're working on upgrading a contributed module upgrade, try asking there.

    Found a bug?

    If you run into something that seems like a bug while working on your module upgrade:

    • Search the Drupal 8.x issue queue for an existing bug report.
    • If you find a related bug report, add your information to the issue. You can even test the patch for the issue if there is one!
    • If you don't find an existing bug report, you can file a new issue.

    Developer experience (DX) issue?

    During Drupal 8's development cycle a lot of attention went into providing a great Drupal 8 developer experience (DX). Still there are always things that can improve so if you run into something that makes your developer experience not-so-great while working on your module upgrade, help us fix it! :)

    Unclear documentation?

    If something in a Drupal 8 change record or handbook page is unclear, edit it to make it better! This will help other contributors going forward.

Looking for support? Visit the forums, or join #drupal-support in IRC.


esolitos’s picture

Hi, shouldn't the version be 8.0.x instead of 8.x with the new semantic versioning?

akalata’s picture

Semantic versioning is for core; contrib should still follow the 8.x naming.