Change from ubuntu@24.04 to ubuntu@26.04

This is a guide for migrating a rock that uses ubuntu@24.04 as its base to ubuntu@26.04.

The ubuntu@26.04 base is built from Ubuntu 26.04 LTS. For most rocks, the migration consists of checking dependencies and extensions. The guidelines documented here also apply to the ubuntu@25.10 interim base.

Stability and workarounds

In the wake of a new base, some of the updated features and packages your rock relies on will be unstable for a time.

This is to be expected with complex software. A short-term fix or workaround in your rock’s parts, packages, and scriptlets might be needed. But sometimes a workaround lives longer than originally planned, so it’s a good practice to explain your workarounds with comments in your project’s rockcraft.yaml.

Update the base

Start by updating the base key:

rockcraft.yaml
- base: ubuntu@24.04
+ base: ubuntu@26.04

Check extension support

Not all extensions are compatible with ubuntu@26.04 at launch. If your rock uses an extension, run rockcraft extensions to see if it’s available for ubuntu@26.04. If your rock uses an extension that does not yet support ubuntu@26.04, it’s best to wait to upgrade.

Update part names

If you update a rock to use ubuntu@26.04, then you must also verify its part names. Part names on ubuntu@26.04 and higher bases can’t contain any forward slashes (/). We recommend replacing them with a hyphen (-):

rockcraft.yaml
 base: ubuntu@26.04

 # ...

 parts:
-  my/part:
+  my-part:

Update parts to the new .NET plugin

If your project has a part using the .NET plugin, note that bases ubuntu@25.10 and higher use a new version of the plugin that gives you new options to control the separate steps of the .NET build process. Notable changes include:

  • The key dotnet-configuration replaces dotnet-build-configuration;

  • The key dotnet-self-contained replaces dotnet-self-contained-runtime-identifier. This new key is a boolean and the proper runtime identifier is automatically derived by the plugin.

  • The dotnet-version key is used to let the plugin automatically pull the correct SDK to build the project. If this key is not specified, the SDK must be provided by the user via the standard means: build-packages, build-snaps, or a separate part that provides the SDK.

Update parts to the new Python plugin

Rocks targeting ubuntu@25.10 and higher use a new version of the Python plugin that seamlessly integrates the usrmerge changes implemented in those bases. The two versions of the plugin have the same options, so in most cases the rock should pack and run without manual intervention.

However, there are no equivalent new versions for the uv and Poetry plugins. Users of these plugins should either wait until new versions become available, or should instead use the corresponding tool to generate a requirements specification file that the Python plugin can use.

For example, the following part using the uv plugin in ubuntu@24.04:

rockcraft.yaml
base: ubuntu@24.04

# ...

parts:
  uv-part:
    plugin: uv

    # ...

can be updated to:

rockcraft.yaml
base: ubuntu@26.04

# ...

parts:
  uv-part:
    plugin: python
    python-requirements:
      - uv-requirements.txt # generated by 'override-build'
    override-build: |
      # generate a requirements file from uv.lock
      uv export --quiet --no-hashes --no-dev --no-emit-workspace > uv-requirements.txt
      # call the default build of the python plugin
      craftctl default

    #...

Update packages

Package names and versions change between Ubuntu releases. If you have parts that declare build-packages or stage-packages, those packages may need to be updated in your project file.

Build your rock and note any dependent packages that fail to resolve. Search the Ubuntu package archive for the equivalent on Ubuntu 26.04, and update build-packages and stage-packages accordingly.

A package may have been split, merged, or renamed. When you make a non-obvious substitution, it’s good practice to leave a comment so that future maintainers understand the change:

rockcraft.yaml
stage-packages:
  - libexample3t64  # renamed from libexample3 in Ubuntu 26.04