On October 4, 2021, Netlify will be fully removing support for the Ubuntu 14.04 (Trusty) build image. Trusty has been End of Life since April 25, 2019, which means it hasn’t received security or maintenance updates since then.
Builds on Trusty make up a very small percentage of total Netlify builds, but we know this is a significant change so we’re giving you plenty of time to migrate.
How do I know if my site is using Trusty?
If you’re not sure whether your site is building with Trusty, you can check in two places:
- You sites list or site detail page. Sites using the Trusty image have a
warning icon next to the site name. - Your deploy logs. Check for a log line that says:
DEPRECATION NOTICE: Builds using the Trusty build image will fail after October 4, 2021 - Your site settings. Go to Site settings > Build & deploy > Continuous Deployment > Build image selection.
What’s different about the new build image?
In May, we released a new build image based on Ubuntu 20.04 (Focal). In addition to a newer version of Ubuntu Linux, it includes some version updates to included language and software dependencies. Some dependency versions that were included in the Trusty image are not included in the Focal image. This may cause issues for sites that relied on those versions.
What will happen if I don’t update my site’s build image?
After October 4, any new builds using the Trusty build image will fail. We will continue to serve traffic to your existing site, and you will still be able to deploy manually via Netlify CLI, but you will not be able to run new builds of your site on Netlify until you update to a newer build image.
How do I update my build image?
You can select a different build image in the Netlify UI under Site settings > Build & deploy > Continuous Deployment > Build image selection.
If you have several sites to update, you can migrate to Focal in bulk using @jlengstorf’s npm package: ntl-focal-migrate - npm
Before making this change to a critical or production site, we recommend running a test build first.
How can I run a test build with the new image?
One way to run a test build is through the Netlify UI:
-
From your site’s Deploys page, select the current published deploy (usually the most recent production deploy).
-
At the top of the deploy’s log page, click the button, Lock publishing to this deploy. With deploys locked, you can run new deploys without changing your published site.
-
Click the Deploy settings button, scroll down to Build image selection, and select a newer build image. We strongly recommend Focal since it has the latest software. The Xenial image will be deprecated later this year.
-
Go back to your Deploys page and click the Trigger deploy button.
-
The new deploy will start building. If it succeeds, click Preview deploy to visit that version of your site. If the site is working normally, you’re set! Go back to your Deploys page and click Start auto-publishing to keep builds running normally, now with their fancy new build image.
-
If the deploy fails or the site isn’t working properly, you will need to do some troubleshooting. If you don’t have time to do that now, you can switch back to the Trusty image and Start auto-publishing again. You can repeat the steps above when you’re ready to troubleshoot, or create a new site for testing that’s linked to the same repository. Here’s how:
- Create a brand new site by clicking the New site from Git button on your team dashboard. Be sure to link to the same repository that you use for your existing site!
- Once you’ve created your new site, go to Site settings > Build & deploy > Continuous Deployment > Build image selection and select the new build image.
- Trigger a deploy to test the new build image.
How can I make my site work with the new image?
Generally speaking, a change in available language or software dependency versions is the cause of the error. This could be a version you set yourself, or one that was set for you by default when the site was first created. Here are some general steps for troubleshooting:
-
Check for error messages in the deploy log. They will often indicate which language or software dependency is causing the problem.
-
Check the Focal image included software list to find which versions are available for the dependency that is causing your issue.
-
Try setting the dependency to use an included version. Refer to the docs on managing dependencies to learn how to do this.
Note: if the dependency version was not explicitly set by you, then it’s set to a version selected by default when you created your site. You can override this as described in the dependency management docs. Select a version already installed on the image to avoid unneeded installations.
If you prefer not to set a version explicitly, you can “reset” your site defaults by re-linking your site repository, but please note that this will also remove any environment variables set in the Netlify UI. Be sure to copy your variables before re-linking, then re-enter them after re-linking.
-
Run a new test build to see if it works.
-
If it doesn’t work, and you’ve tried all available versions on the new image, you may have the option to specify a version that isn’t pre-installed on the image. Dependencies with this option are labeled in the included software list with “Any version” as one of the version options.
-
For dependencies that don’t offer an option to download any version, such as Python and PHP, you will need to update your site code to work with a version available on the new image. You can search for migration guides for the dependency version to help you identify necessary changes.
If you get through these steps and you’re still stuck, or if you have any other questions along the way, let us know!
.
.