---
title: "Zephyr 2.5 Update"
authors: petejohanson
tags: [firmware, zephyr, core]
---

I'm happy to announce that we have completed the [work](https://github.com/zmkfirmware/zmk/pull/736/) to upgrade ZMK to [Zephyr 2.5](https://docs.zephyrproject.org/2.5.0/releases/release-notes-2.5.html)!

<!-- truncate -->

A big part of this work was some _major_ refactors and improvements by [innovaker] to our [zmk-docker](https://github.com/zmkfirmware/zmk-docker/) Docker image and GH Actions automation.

- Faster build times with improved caching.
- Integration tests which automatically verify new images.
- PRs to the repo now build properly and run the tests as well.
- Build images for multiple target architectures, e.g. `zmk-build-riscv64`, all in parallel.
- Nightly builds to be sure we're pulling in the latest OS/package updates, to ensure we keep our images up to date, address any reported vulnerabilities, etc.
- Faster upgrade paths for future Zephyr SDK and Zephyr versions.

In addition, [petejohanson] did the upgrade work to adjust ZMK for the Zephyr changes.

- Updated to newer devicetree/driver Zephyr API
- Adjustment for Zephyr pinmux changes
- Fixes for power management, LVGL, and formatter changes

## Getting The Changes

Use the following steps to update to the latest tooling in order to properly use the new ZMK changes:

### User Config Repositories Using GitHub Actions

Existing user config repositories using Github Actions to build will pull down Zephyr 2.5 automatically,
and should work, fine as is. However, to upgrade to the newer Docker image, you should:

- Open `.github/workflows/build.yml` in your editor/IDE
- Change `zmkfirmware/zmk-build-arm:2.4` to `zmkfirmware/zmk-build-arm:2.5` wherever it is found

:::note

If you created your user config repository a while ago, you may find that your `build.yml` file instead references
a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that
instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation
approach.

:::

### VS Code & Docker (Dev Container)

If you build locally using VS Code & Docker then:

- pull the latest ZMK `main` with `git pull` for your ZMK checkout
- reload the project
- if you are prompted to rebuild the remote container, click `Rebuild`
- otherwise, press `F1` and run `Remote Containers: Rebuild Container`
- Once the container has rebuilt and reloaded, run `west update` to pull the updated Zephyr version and its dependencies.

Once the container has rebuilt, VS Code will be running the 2.5 Docker image.

### Local Host Development

The following steps will get you building ZMK locally against Zephyr 2.5:

- Run the updated [toolchain installation](/docs/development/local-toolchain/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- pull the latest ZMK `main` with `git pull` for your ZMK checkout
- run `west update` to pull the updated Zephyr version and its dependencies

From there, you should be ready to build as normal!

## Thanks!

Thanks again to [innovaker] for all the hard work, and to all the testers who have helped verify ZMK functionality on the newer Zephyr version.

[petejohanson]: https://github.com/petejohanson
[innovaker]: https://github.com/innovaker