# Upgrade NGINX Agent

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

---


## Overview

**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"
        ```

## Migrate NGINX Agent running in containers

To migrate NGINX Agent containers, we provide a script to convert NGINX Agent v2 config files to NGINX Agent v3 config files: [NGINX Agent Config Upgrade Script](https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh)

To upgrade the configuration, you can follow this example:

```shell
wget https://raw.githubusercontent.com/nginx/agent/refs/heads/main/scripts/packages/upgrade-agent-config.sh
./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=nginx-agent-v3.conf
```

If your NGINX Agent container was previously a member of a Config Sync Group, then your NGINX Agent config must be manually updated to add the Config Sync Group label.
See [Add Config Sync Group](/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md) for more information.

### Rolling back from NGINX Agent v3 to v2

If you need to roll back your environment to NGINX Agent v2, the upgrade process creates a backup of the NGINX Agent v2 config in the file `/etc/nginx-agent/nginx-agent-v2-backup.conf`.

Replace the contents of `/etc/nginx-agent/nginx-agent.conf` with the contents of `/etc/nginx-agent/nginx-agent-v2-backup.conf` and then reinstall an older version of NGINX Agent.