﻿---
title: Upgrade standalone Elastic Agents
description: The upgrade method depends on how you installed Elastic Agent: TAR/ZIP installations (macOS, Linux, Windows): Use the elastic-agent upgrade command as...
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5645/reference/fleet/upgrade-standalone
products:
  - Elastic Agent
  - Fleet
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available
---

# Upgrade standalone Elastic Agents
The upgrade method depends on how you installed Elastic Agent:
- **TAR/ZIP installations** (macOS, Linux, Windows): Use the `elastic-agent upgrade` command as described in [Upgrade TAR and ZIP installations](#upgrade-standalone-tar-zip).
- **DEB and RPM installations** (Linux): Use your system's package manager as described in [Upgrade DEB and RPM installations](#upgrade-standalone-deb-rpm).


## Upgrade TAR and ZIP installations

To upgrade a standalone Elastic Agent installed from a TAR or ZIP archive:
1. Make sure the `elastic-agent` service is running.
2. From the directory where Elastic Agent is installed, run the `upgrade` command to upgrade to a new version. Not sure where the agent is installed? Refer to [Installation layout](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5645/reference/fleet/installation-layout).
   For example, to upgrade the agent to 9.3.2:
   <tab-set>
   <tab-item title="macOS">
   ```shell
   sudo elastic-agent upgrade 9.3.2
   ```
   </tab-item>

   <tab-item title="Linux">
   ```shell
   sudo elastic-agent upgrade 9.3.2
   ```
   </tab-item>

   <tab-item title="Windows">
   As an Administrator, run:
   ```shell
   .\elastic-agent.exe upgrade 9.3.2
   ```
   </tab-item>
   </tab-set>

This command upgrades the binary. Your agent policy should continue to work, but you might need to upgrade it to use new features and capabilities.
For more command-line options, check the help for the [`upgrade`](/elastic/docs-content/pull/5645/reference/fleet/agent-command-reference#elastic-agent-upgrade-command) command.

## Upgrade DEB and RPM installations

<note>
  TAR/ZIP installations are recommended over system-managed packages because they can be enrolled and managed in Fleet.
</note>

For Elastic Agents installed using DEB or RPM packages, you must use your system's package manager to upgrade. The `elastic-agent upgrade` command is not supported for system-managed packages.
<tab-set>
  <tab-item title="DEB">
    1. Download the Elastic Agent Debian install package for the release and architecture that you want to upgrade to. For example, to upgrade to 9.3.2:
       For x86_64 (64-bit Intel/AMD):
       ```bash
       curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-9.3.2-amd64.deb
       ```
       For ARM64 (aarch64):
       ```bash
       curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-9.3.2-arm64.deb
       ```
    2. Upgrade Elastic Agent to the target release. Replace the filename with the package you downloaded:
       ```bash
       sudo dpkg -i elastic-agent-9.3.2-amd64.deb
       ```
    3. Restart the Elastic Agent service:
       ```bash
       sudo systemctl restart elastic-agent
       ```
  </tab-item>

  <tab-item title="RPM">
    1. Download the Elastic Agent RPM install package for the release and architecture that you want to upgrade to. For example, to upgrade to 9.3.2:
       For x86_64 (64-bit Intel/AMD):
       ```bash
       curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-9.3.2-x86_64.rpm
       ```
       For ARM64 (aarch64):
       ```bash
       curl -L -O https://artifacts.elastic.co/downloads/beats/elastic-agent/elastic-agent-9.3.2-aarch64.rpm
       ```
    2. Upgrade Elastic Agent to the target release. Replace the filename with the package you downloaded:
       ```bash
       sudo rpm -U elastic-agent-9.3.2-x86_64.rpm
       ```
    3. Restart the Elastic Agent service:
       ```bash
       sudo systemctl restart elastic-agent
       ```
  </tab-item>
</tab-set>


## Upgrading standalone Elastic Agent in an air-gapped environment

The basic upgrade scenario should work for most use cases. However, in an air-gapped environment Elastic Agent is not able to access the Elastic Artifact Registry at `artifacts.elastic.co` directly.
As an alterative, you can do one of the following:
- [Configure a proxy server](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5645/reference/fleet/fleet-agent-proxy-support) for standalone Elastic Agent to access the Elastic Artifact Registry.
- [Host your own artifact registry](/elastic/docs-content/pull/5645/reference/fleet/air-gapped#host-artifact-registry) for standalone Elastic Agent to access binary downloads.

As well, starting from version 8.9.0, during the upgrade process Elastic Agent needs to download a PGP/GPG key. Refer to [Configure Elastic Agents to download a PGP/GPG key from Fleet Server](/elastic/docs-content/pull/5645/reference/fleet/air-gapped#air-gapped-pgp-fleet) for the steps to configure the key download location in an air-gapped environment.
Refer to [Air-gapped environments](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5645/reference/fleet/air-gapped) for more details.

## Verifying Elastic Agent package signatures

Standalone Elastic Agent verifies each package that it downloads using publicly available SHA hash and .asc PGP signature files. The SHA file is used to verify that the package has not been modified, and the .asc file is used to verify that the package was released by Elastic. For this purpose, the Elastic public GPG key is embedded in Elastic Agent itself.
At times, the Elastic private GPG key may need to be rotated, either due to the key expiry or due to the private key having been exposed. In this case, standalone Elastic Agent upgrades can fail because the embedded public key no longer works.
In the event of a private GPG key rotation, you can use the following options with the [`upgrade`](/elastic/docs-content/pull/5645/reference/fleet/agent-command-reference#elastic-agent-upgrade-command) command to either skip the verification process (not recommended) or force Elastic Agent to use a new public key for verification:
<definitions>
  <definition term="--skip-verify">
    Skip the package verification process. This option is not recommended as it is insecure.
    Example:
    ```yaml
    ./elastic-agent upgrade 9.3.2 --skip-verify
    ```
  </definition>
  <definition term="--pgp-path <string>">
    Use a locally stored copy of the PGP key to verify the upgrade package.
    Example:
    ```yaml
    ./elastic-agent upgrade 9.3.2 --pgp-path /home/elastic-agent/GPG-KEY-elasticsearch
    ```
  </definition>
  <definition term="--pgp-uri <string>">
    Use the specified online PGP key to verify the upgrade package.
    Example:
    ```yaml
    ./elastic-agent upgrade 8.7.0-SNAPSHOT --pgp-uri "https://artifacts.elastic.co/GPG-KEY-elasticsearch"
    ```
  </definition>
</definitions>

Under the basic upgrade scenario standalone Elastic Agent automatically fetches the most current public key, however in an air-gapped environment or in the event that the Elastic Artifact Registry is otherwise inaccessible, these commands can be used instead.

## Roll back an Elastic Agent upgrade for standalone agents

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.3
</applies-to>

We have you covered in the unusual case that you need to rollback an upgrade for a standalone agent.
<admonition title="Elastic subscription">
  The manual rollback feature for Elastic Agent is available only for some [Elastic subscription levels](https://www.elastic.co/subscriptions).
</admonition>

**Manual rollback.**
The manual rollback feature expands the time window for rollbacks, giving you the ability to roll back to the previous version within seven days.
To roll back a recent upgrade to the previously installed version (if it is still available on disk):
<tab-set>
  <tab-item title="macOS">
    ```shell
    sudo elastic-agent upgrade --rollback
    ```
  </tab-item>

  <tab-item title="Linux">
    ```shell
    sudo elastic-agent upgrade --rollback
    ```
  </tab-item>

  <tab-item title="Windows">
    As an Administrator, run:
    ```shell
    .\elastic-agent.exe upgrade --rollback
    ```
  </tab-item>
</tab-set>

<note>
  The manual rollback feature is not available for system-managed packages such as DEB and RPM.
</note>


### Limitations for manual rollback (standalone agents)

These limitations apply for the manual rollback feature:
- Rollback is limited to the version running _before_ the upgrade. Both the previously and currently running versions must be 9.3.0 or later for this functionality to be available.
- Data required for the rollback is stored on disk for seven days, which can impact available disk space.
- Rollback must be performed within seven days of the upgrade. Rollback data is automatically cleaned up after seven days and becomes unavailable.
- Manual rollback is not available for system-managed packages such as DEB and RPM.
- Some data might be re-ingested after rollback.


#### Possible errors

If no version is available on disk to rollback to, you get an error.
This situation can happen if:
- the version you upgraded from is earlier than 9.3.0, as the feature was not implemented in earlier versions.
- the rollback window has ended (typically more than seven days). When the rollback window ends, the files from the previous version are removed to free up disk space.