# Upgrade NGINX Agent package

Type of document: How-to guide
Product: NGINX Agent

---


## Overview

Learn how to upgrade NGINX Agent.

## Upgrade NGINX Agent

**Note:**  If you are using a version **older than NGINX Agent v2.31.0**, you must stop NGINX Agent before updating:

   - `sudo systemctl stop nginx-agent`

And start it again after the update or upgrade:

   - `sudo systemctl start nginx-agent`

Follow the steps below to update or upgrade NGINX Agent to the latest version.
The same steps apply if you are **upgrading from NGINX Agent v2 to NGINX Agent v3**.

1. Open an SSH connection to the server where you've installed NGINX Agent.

1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade does not complete
   successfully:

    - `/etc/nginx-agent`
    - Every configuration directory specfied in `/etc/nginx-agent/nginx-agent.conf` as a `config_dirs` value

1. Install the updated version of NGINX Agent:

    - CentOS, RHEL, RPM-Based

        ```shell
        sudo yum -y makecache
        sudo yum update -y nginx-agent
        ```

    - Debian, Ubuntu, Deb-Based

        ```shell
        sudo apt-get update
        sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold"
        ```

## Upgrade NGINX Agent to a Specific Version

To upgrade NGINX Agent to a specific **v2.x version**, follow these steps:

1. Open an SSH connection to the server running  NGINX Agent and log in.

1. Back up the following files and directories to ensure you can restore the environment in case of issues during the upgrade:

    - `/etc/nginx-agent`
    - Any `config_dirs` directory specified in `/etc/nginx-agent/nginx-agent.conf`.

1. Perform the version-controlled upgrade.

   - Debian, Ubuntu, Deb-Based

        ```shell
        sudo apt-get update
        sudo apt-get install -y nginx-agent=<specific-version> -o Dpkg::Options::="--force-confold"
        ```

        Example (to upgrade to version 2.42.0~noble):

        ```shell
        sudo apt-get install -y nginx-agent=2.42.0~noble -o Dpkg::Options::="--force-confold"
        ```

    - CentOS, RHEL, RPM-Based

        ```shell
        sudo yum install -y nginx-agent-<specific-version>
        ```

        Example (to upgrade to version `2.42.0`):

        ```shell
        sudo yum install -y nginx-agent-2.42.0
        ```

1. Verify the installed version:

    ```shell
    sudo nginx-agent --version
    ```