Note: As of November 2021, this guide is no longer accurate as a new build image was released in 2021. The Trusty build image will no longer work on our system. Please see the guide on migrating to the new Focal build image in the comment after this post. If you have questions about migrating your project, please start a new thread, as this thread is locked. thanks! --Support at Netlify
Skip to the end! Just tell us what we need to know!
Let me “skip ahead” to the answer to the second question above. At present, the recommended build image is the Xenial image.
This is also the build image which all new sites use by default so, if you don’t change the defaults, your site will automatically use the recommended image: Xenial.
If you want to know more about the two build images, please keep reading.
Background
Originally, there was only a single “build image” - the Trusty image.
What is a “build image” you ask? The answer is that a “build image” is the virtual machine (VM) image we use for site builds at Netlify. This defines the set of software which is available by default to build sites.
We have two different build images to choose from currently. Each one is based on a specific version of Ubuntu Linux: version 14.04 (Trusty Tahr) and 16.04 (Xenial Xerus). We refer to those two build images by their Ubuntu Linux version names, “Trusty” and “Xenial”.
If you are curious about what each build image includes for software, those details can be found using the two links below:
https://github.com/netlify/build-image/blob/trusty/included_software.md
https://github.com/netlify/build-image/blob/xenial/included_software.md
The Trusty build image used to be the only build image available. The Xenial image was added later and it is current the automatically chosen default build image for all newly created sites at Netlify. (You can still use Trusty though if you want to. We strongly recommend Xenial though.)
Important differences of the Xenial build image
So, why would the Xenial image be recommended? Well, besides being a more recent Ubuntu release, our “latest and greatest” new features will only work and be supported under Xenial.
Those features include:
- the monorepo support added October of 2019
- build plugin support
- bugfixes (bugfixes in Xenial are not back ported to Trusty unless they are required for security reasons)
What is the suggested migration process to move a site from Trusty to Xenial?
If you have an existing site and want to move it to the Xenial build image, we recommend making a new site and linking that site to the existing repo. Yes, you can have a single repo linked to multiple sites.
The new site will use Xenial by default. If the build and deploy is successful, next check the new site to confirm that it was built correctly.
Once you are satisfied that the site is created correctly with the new build image, you can change the build image for the original site under Site name > Settings > Build & deploy > Build image selection
. Click the “Edit Settings” button, then select the “Ubuntu Xenial 16.04” option, and then click “Save”. The next deploy of this site will now use the Xenial build image instead.
How do I know what build image my site is using?
One method is to check the setting listed above (Site name > Settings > Build & deploy > Build image selection
).
You can also see the version at the beginning of the build logs for a deploy. If the site uses Trusty the version will begin with “v2”. For example:
7:38:35 PM: build-image tag: v2.8.2
If the site uses Xenial it will begin with “v3”, similar to this:
2:33:25 AM: build-image tag: v3.3.14
Summary
We hope this answers most of your questions about the two different build images. If there are other questions which aren’t answered by this topic, please ask those questions below and we’ll do our best to answer.