---
schema_version: "1"
id: a2e78aaa4608b01dc66a595dfd55d70a72d6d04b621dc4559adb853d1e089314
title: Upgrading Mule Runtime Engine (Versions 4.x to 4.n)
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/release-notes/mule-runtime/updating-mule-4-versions.md
canonical_url: https://docs.mulesoft.com/release-notes/mule-runtime/updating-mule-4-versions
source_site: docs.mulesoft.com
content_type: documentation
content_hash: d1a9bdfcd9b543dfeadad813a1a22a0fe14229fdd21fa0749e762d4a7b9927c5
description: MuleSoft Documentation Site
latest: true
---
---
product: Release Notes
version: master
keywords: mule, runtime, release notes, migration, installation, downtime, uptime, best practices
---

# Upgrading Mule Runtime Engine (Versions 4.x to 4.n)

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To upgrade your current Mule instance to a later release of Mule runtime engine (version 4.x), you
must follow some best practices. The following steps and recommendations help you to:

- Upgrade your standalone Mule instances.

- Upgrade your on-premises Mule instances managed through Runtime Manager.

- Change the Mule version used to build your Mule applications, if necessary.

To change the Mule runtime engine version of your CloudHub workers, you need to use the
[runtime version drop-down box](https://docs.mulesoft.com/cloudhub/deploying-to-cloudhub#runtime-tab) in the application
settings deployment configuration page.

## Ensuring Mule Application Compatibility

When you create a Mule application, you select the Mule runtime engine version that your application
is intended to run on. This is the target Mule version of an application.

Because Mule runtime engine uses semantic versioning (MAJOR.MINOR.PATCH), Mule applications are:

- Rarely compatible between _major_ releases (3.9.3 to 4.1.0, for example).

- Potentially compatible between _minor_ releases (4.1.0 to 4.2.0, for example).

- Fully compatible between _patch_ releases (4.1.4 to 4.1.5 for example).

Note that Mule provides a feature flagging mechanism that enables Mule applications to change the
behavior of the Mule instance depending on the minimum Mule version (`minMuleVersion`). This feature
ensures backward compatibility because it enables Mule applications to continue working on later
Mule runtime versions, while new Mule applications can benefit from the latest bug fixes implemented
in the Mule instance. For details, see
[Feature Flagging Mechanism](https://docs.mulesoft.com/mule-runtime/latest/feature-flagging).

Read the [release notes](https://docs.mulesoft.com/release-notes/mule-runtime/mule-esb) for the Mule runtime engine version that you want to upgrade to
and verify if you must make any compatibility changes to your Mule applications.

MuleSoft recommends executing a regression test cycle to validate compatibility between minor
releases.

For Mule 4.5 and later, the version naming convention for CloudHub, CloudHub 2.0, and Runtime Fabric
changes following the schema for the new release channels, Edge and Long-term Support (LTS).

_Major\[numeric\] . Minor\[numeric\] . Patch\[numeric\] : Build\[numeric\] Channel\[e for edge,
nothing for LTS\]_

Here are examples of the version numbers:

- Edge: 4.5.0:1e

- Edge: 4.6.0:1e

- LTS: 4.6.0:1

In the case of Standalone (On-Premises), the Mule runtime versioning changes from date-based, for
example, `4.4.0-20230317` to semVer as:

_Major\[numeric\] . Minor\[numeric\] . Patch\[numeric\]_

Here are examples of the version numbers:

- 4.5.1

- 4.5.2

- 4.5.3

See [Edge and LTS Releases for Mule](https://docs.mulesoft.com/release-notes/mule-runtime/lts-edge-release-cadence).

### Changing the Target Mule Version of your Mule Application

In case you need to change your Mule application’s target Mule version, follow these steps:

1.  [Download the desired Mule runtime engine](https://docs.mulesoft.com/studio/studio-update-sites#mule-runtimes-for-anypoint-studio-update-site)
    in Anypoint Studio so that you can select that version in the IDE.

2.  For every application that you upgrade:

    1.  [Import the application](https://docs.mulesoft.com/studio/import-export-packages#importing-projects-to-studio)
        to Anypoint Studio as a Mule project.

    2.  During the import process remember to change the target Mule version by selecting it from
        the **Server Runtime** menu.

        ![updating mule versions 415](/mulesoft/current/en-us/release-notes/_images/mule-runtime/updating-mule-versions-415.png)

    3.  Make any other changes necessary to ensure compatibility with the Mule version you are
        transitioning to.

    4.  [Export your project](https://docs.mulesoft.com/studio/import-export-packages#exporting-projects-from-studio) as
        a Mule Deployable Archive (`.jar` file).

    5.  Edit the `pom.xml` file to make the `muleVersion` property value match the target Mule
        version.

After you have successfully built the Mule Deployable Archives (`.jar` files) with the new target
Mule version, and you have applied any other necessary changes to ensure compatibility, you can move
on to upgrading the corresponding Mule runtime engine instances.

## Upgrading a Standalone Mule Instance

Use the Mule upgrade tool to automate the upgrade process of your local Mule instances. Visit
[Mule upgrade tool](https://docs.mulesoft.com/mule-runtime/latest/mule-upgrade-tool) for installation and usage
instructions.

Optionally, you can also perform a completely manual update of your Mule instances. To ensure less
downtime and easier backups during manual upgrades, first install the new Mule runtime engine on a
separate server from that on which your current Mule runtime engine is installed. That way you can
set everything up and only then initiate the new Mule instance and decouple the previous one.

> [!NOTE] If you are upgrading Mule in the same server or virtual machine, ensure that you
> [remove](https://docs.mulesoft.com/on-premises/latest/starting-and-stopping-mule-esb#removing-the-mule-service-or-daemon)
> the Mule service or daemon before you install the new Mule runtime engine as a service.

### Steps to Manually Upgrade the Mule Instance

1.  From the Customer Portal, download the Mule runtime engine version you want to upgrade to.

2.  If you run Mule as a service, install the new Mule version on a different server or virtual
    machine:

    - `$MULE_HOME\bin\mule.bat install` on Windows systems

    - `$MULE_HOME/bin/mule install` on Linux/Unix systems

3.  Download a new copy of your license from the Customer Portal and install it on the new Mule
    instance (see
    [Installing an Enterprise License](https://docs.mulesoft.com/on-premises/latest/installing-an-enterprise-license)
    for instructions).

4.  If you have custom configurations in your previous Mule instance (for example, if you defined a
    different maximum heap size in the `wrapper.conf` file), replicate these settings in the new
    Mule instance.

5.  [Run your new Mule instance](https://docs.mulesoft.com/on-premises/latest/starting-and-stopping-mule-esb#running-mule)
    to verify that your installation is working as expected.

6.  After considering possible negative impact, you can shut down your previous Mule instance at
    this point.

7.  If you set environment variables such as `MULE_HOME` or `PATH`, verify that they point to the
    new Mule runtime engine’s installation path.

8.  Deploy your applications to your new Mule instance.

## Upgrading an On-Premises Mule Instance Managed Through Runtime Manager

Use the Mule upgrade tool to automate the upgrade process of your local Mule instances. Visit
[Mule upgrade tool](https://docs.mulesoft.com/mule-runtime/latest/mule-upgrade-tool) for installation and usage
instructions.

Optionally, you can also perform a completely manual update of your on-premises Mule instances. To
ensure less downtime and easier backups, first install the new Mule runtime engine on a separate
server from that on which your current Mule runtime engine is installed. That way you can set
everything up. Shut down the previous Mule instance and only then initiate the new Mule instance.

To manually migrate following these steps, you must have the
[Runtime Manager Agent](https://docs.mulesoft.com/runtime-manager/runtime-manager-agent) installed.

### Steps to Manually Upgrade the Mule Instance

1.  Go through steps 1 through to 5 of the previous section,
    [Upgrading a Standalone Mule Instance](#upgrading-a-standalone-mule-instance).

2.  Copy the following three files from `<MULE_HOME>/conf` from your previous Mule instance into the
    same folder on the new Mule instance:

    - `mule-agent.yml`

    - `mule-agent.jks`

    - `truststore.jks` and/or `anypoint-truststore.jks`

3.  Copy the `mule-agent-plugin` folder from `<MULE_HOME>/server-plugins` from your previous Mule
    instance into the same folder on the new Mule instance.

4.  Shut down the previous Mule instance.

5.  Open a terminal window and navigate to the `<MULE_HOME>/bin` directory of your new Mule
    instance.

6.  Run the following command:

    amc\_setup -U

    This command installs the latest version of the Runtime Manager Agent on your new Mule instance,
    ensuring compatibility. The files you copied from your previous Mule instance hold all of the
    configuration information to register the new Mule instance on Runtime Manager.

    Even when you’re installing your new Mule version on another server or VM, the copied
    configuration files should suffice to smoothly transition the Mule instance’s identity on
    Runtime Manager.

    If your previous Mule instance has apps deployed through Runtime Manager, there’s no need to
    manually copy them, as they automatically upload to your new Mule instance. This process
    automatically redeploys the applications to the new instance.

    If your previous Mule instance has apps that were manually deployed, you need to manually
    redeploy them.

    > [!CAUTION] Applications must be running and showing as `Started` in Runtime Manager. This
    > process does not migrate stopped Applications.

7.  At this point, your Mule instance is upgraded to the desired Mule version. Updating the target
    Mule version of your deployed applications is optional. If you decide to do so, then you must
    also:

    1.  Follow the steps in
        [Changing the Target Mule Version of your Mule Application](#changing-the-target-mule-version-of-your-mule-application).

    2.  Find the application on the **Applications** tab on Runtime Manager and click **Choose
        File** to
        [upload](https://docs.mulesoft.com/runtime-manager/managing-deployed-applications#updating-your-application) the
        new Mule Deployable Archive (`.jar` file).

### Considerations About Clusters

After you complete the manual upgrade steps for your on-premises Mule instance, copy the
`mule-cluster.properties` file from folder `<MULE_HOME>/.mule` in the previous Mule instance to the
same folder in the new Mule instance. If the `.mule` folder does not exist in the new Mule instance,
create the folder and then copy the file.

Zero downtime cannot be guaranteed when upgrading the Mule runtime engine version of your Runtime
Manager clusters. At some point during the upgrade, the cluster is in a mixed state, with coexisting
nodes running two different Mule versions. This might lead to incompatible communication protocols
between Hazelcast instances. When such errors occur, every node in the cluster must be shut down to
proceed with the upgrade.

## Upgrade the Mule Runtime Version in a Runtime Manager Server Group

Follow these steps to upgrade the Mule version in a Runtime Manager server group:

1.  Go to Anypoint Runtime Manager.

2.  Switch to the corresponding environment.

3.  Select **Servers** in the navigation menu.

4.  Select the server group to update.

    1.  In the server group dashboard, select the **Servers** tab and select the server to upgrade.

    2.  In the actions dropdown menu, select **Shutdown**.

    3.  Repeat the previous two steps for each server in your server group.

5.  Open a terminal in the local machine that hosts your Mule instance.

6.  If your Runtime Manager agent version is earlier than 2.2.0, upgrade to the latest version.

    Go to the current Mule Home directory and run the following commands:

    `cd ${MULE-4.1.5_HOME}/bin`

    `cp ~/Downloads/agent-setup-2.4.20.zip .`

    `unzip agent-setup-2.4.20.zip`

    `./amc_setup -U`

7.  Go to the target directory for the new Mule runtime version and install it:

    `cd ${MULE-4.3.0_DIRECTORY}`

    `cp ~/Downloads/mule-ee-distribution-standalone-4.3.0.zip .`

    `unzip mule-ee-distribution-standalone-4.3.0.zip`

8.  Install the latest agent version:

    `cd mule-enterprise-standalone-4.3.0/bin`

    `cp ~/Downloads/agent-setup-2.4.20.zip .`

    `unzip agent-setup-2.4.20.zip`

    `./amc_setup -I`

    `rm ../conf/mule-agent.yml`

9.  Copy the following files from the previous Mule runtime `/conf` directory to the new Mule
    runtime `/conf` directory:

    - All YAML files (`*.yml`)

    - All keystore files (`*.jks`)

10. Confirm that the DNS configured in `mule-agent.yml` has the following values:

    websocket.transport: consoleUri: wss://runtime-manager.anypoint.mulesoft.com:443/mule

    authenticationProxy: endpoint: https://data-authenticator.anypoint.mulesoft.com

11. If you installed domains in your previous Mule instance, copy those domains to your new Mule
    instance:

    `cp -R ${MULE-4.1.5_HOME}/domains${MULE-4.3.0_HOME}/domains`

12. Start Mule:

    `cd ${MULE-4.3.0_HOME}/bin`

    `./mule start`

13. Go to Runtime Manager to confirm that your Mule applications are deployed and displayed as
    **Running**.

## Upgrading from Mule 4.2 or 4.1 to Mule 4.3 or Later

If you are upgrading from Mule 4.2.x or 4.1.x to Mule 4.3.x or later Mule 4 releases, take the
following actions:

- If no custom threading settings are applied (either through `scheduler-pools.conf` or directly in
  the Mule app), then no action is required.

- If custom threading configurations are applied, test your Mule applications using the default
  configuration.  
  Because of the UBER pool strategy and other performance updates implemented in Mule 4.3, you might
  not need custom threading configurations.

- If tests confirm that a custom configuration is still necessary, a problem might exist with
  resource management in the application, one of the application dependencies, or the Mule instance.

## See Also

- [Mule Upgrade Tool](https://docs.mulesoft.com/mule-runtime/latest/mule-upgrade-tool)

- [Mule Standalone Installation](https://docs.mulesoft.com/on-premises/latest/runtime-installation-task)

- [Runtime Manager](https://docs.mulesoft.com/runtime-manager/)

- [Known Issues](https://help.salesforce.com/s/issues)