# Managing Amazon SAM CLI versions
Manage your Amazon Serverless Application Model Command Line Interface (Amazon SAM CLI) versions through upgrading, downgrading, and uninstalling. Optionally, you can download and install the Amazon SAM CLI nightly build.
**Topics**
+ [Upgrading the Amazon SAM CLI](#manage-sam-cli-versions-upgrade)
+ [Uninstalling the Amazon SAM CLI](#manage-sam-cli-versions-uninstall)
+ [Switch from using Homebrew to manage the Amazon SAM CLI](#manage-sam-cli-versions-switch)
+ [Managing the Amazon SAM CLI nightly build](#manage-sam-cli-versions-nightly-build)
+ [Installing the Amazon SAM CLI into a virtual environment using pip](#manage-sam-cli-versions-install-virtual)
+ [Managing the Amazon SAM CLI with Homebrew](#manage-sam-cli-versions-homebrew)
+ [Troubleshooting](#manage-sam-cli-versions-troubleshoot)
## Upgrading the Amazon SAM CLI
### Linux
To upgrade the Amazon SAM CLI on Linux, follow the installation instructions in [Installing the Amazon SAM CLI](install-sam-cli.md#install-sam-cli-instructions), but add the `--update` option to the install command, as follows:
```
sudo ./sam-installation/install --update
```
### macOS
The Amazon SAM CLI must be upgraded through the same method used to install it. We recommend that you use the package installer to install and upgrade the Amazon SAM CLI.
To upgrade the Amazon SAM CLI using the package installer, install the latest package version. For instructions, see [Installing the Amazon SAM CLI](install-sam-cli.md#install-sam-cli-instructions).
### Windows
To upgrade the Amazon SAM CLI, repeat the Windows installation steps in [Install the Amazon SAM CLI](install-sam-cli.md) again.
## Uninstalling the Amazon SAM CLI
### Linux
To uninstall the Amazon SAM CLI on Linux, you must delete the symlink and installation directory by running the following commands:
1. Locate the symlink and install paths.
+ Find the symlink using the **which** command:
```
which sam
```
The output shows the path where the Amazon SAM binaries are located, for example:
```
/usr/local/bin/sam
```
+ Find the directory that the symlink points to using the **ls** command:
```
ls -l /usr/local/bin/sam
```
In the following example, the installation directory is `/usr/local/aws-sam-cli`.
```
lrwxrwxrwx 1 ec2-user ec2-user 49 Oct 22 09:49 /usr/local/bin/sam -> /usr/local/aws-sam-cli/current/bin/sam
```
1. Delete the symlink.
```
sudo rm /usr/local/bin/sam
```
1. Delete the installation directory.
```
sudo rm -rf /usr/local/aws-sam-cli
```
### macOS
Uninstall the Amazon SAM CLI through the same method that was used to install it. We recommend that you use the package installer to install the Amazon SAM CLI.
If you installed the Amazon SAM CLI using the package installer, follow these steps to uninstall.
**To uninstall the Amazon SAM CLI**
1. Remove the Amazon SAM CLI program by modifying and running the following:
```
$ sudo rm -rf /path-to/aws-sam-cli
```
1. *sudo* – If your user has write permissions to where the Amazon SAM CLI program is installed, **sudo** is not required. Otherwise, **sudo** is required.
1. */path-to* – Path to where you installed the Amazon SAM CLI program. The default location is `/usr/local`.
1. Remove the Amazon SAM CLI `$PATH` by modifying and running the following:
```
$ sudo rm -rf /path-to-symlink-directory/sam
```
1. *sudo* – If your user has write permissions to `$PATH`, **sudo** is not required. Otherwise, **sudo** is required.
1. *path-to-symlink-directory* – Your `$PATH` environment variable. The default location is `/usr/local/bin`.
1. Verify that the Amazon SAM CLI is uninstalled by running the following:
```
$ sam --version
command not found: sam
```
### Windows
To uninstall the Amazon SAM CLI using Windows Settings, follow these steps:
1. From the Start menu, search for "Add or remove programs".
1. Choose the result named **Amazon SAM Command Line Interface**, and then choose **Uninstall** to launch the uninstaller.
1. Confirm that you want to uninstall the Amazon SAM CLI.
## Switch from using Homebrew to manage the Amazon SAM CLI
If you use Homebrew to install and upgrade the Amazon SAM CLI, we recommend using an Amazon supported method. Follow these instructions to switch to a supported method.
**To switch from using Homebrew**
1. Follow instructions at [Uninstalling a Homebrew installed Amazon SAM CLI](#manage-sam-cli-versions-homebrew-uninstall) to uninstall the Homebrew managed version.
1. Follow instructions at [Install the Amazon SAM CLI](install-sam-cli.md) to install the Amazon SAM CLI using a supported method.
## Managing the Amazon SAM CLI nightly build
You can download and install the Amazon SAM CLI nightly build. It contains a pre-release version of the Amazon SAM CLI code that may be less stable than the production version. When installed, you can use the nightly build with the `sam-nightly` command. You can install and use both the production and nightly build versions of the Amazon SAM CLI at the same time.
**Note**
The nightly build does not contain a pre-release version of the build image. Because of that, building your serverless application with the **--use-container** option uses the latest production version of the build image.
### Installing the Amazon SAM CLI nightly build
To install the Amazon SAM CLI nightly build, follow these instructions.
#### Linux
You can install the nightly build version of the Amazon SAM CLI on the Linux x86\$164 platform using the package installer.
**To install the Amazon SAM CLI nightly build**
1. Download the package installer from [sam-cli-nightly](https://github.com/aws/aws-sam-cli/releases/sam-cli-nightly/) in the *aws-sam-cli GitHub repository*.
1. Follow the steps for [installing the Amazon SAM CLI](install-sam-cli.md) to install the nightly build package.
#### macOS
You can install the nightly build version of the Amazon SAM CLI on macOS, using the nightly build package installer.
**To install the Amazon SAM CLI nightly build**
1. Download the package installer for your platform from [sam-cli-nightly](https://github.com/aws/aws-sam-cli/releases/sam-cli-nightly/) in the *aws-sam-cli GitHub repository*.
1. Follow the steps for [installing the Amazon SAM CLI](install-sam-cli.md) to install the nightly build package.
#### Windows
The nightly build version of the Amazon SAM CLI is available with this download link: [Amazon SAM CLI nightly build](https://github.com/aws/aws-sam-cli/releases/download/sam-cli-nightly/AWS_SAM_CLI_64_PY3.msi). To install the nightly build on Windows, perform the same steps as in the [Install the Amazon SAM CLI](install-sam-cli.md), but use the nightly build download link instead.
To verify that you have installed the nightly build version, run the **sam-nightly --version** command. The output of this command is in the form `1.X.Y.dev`, for example:
```
SAM CLI, version 1.20.0.dev202103151200
```
### Switch from Homebrew to the package installer
If you are using Homebrew to install and upgrade the Amazon SAM CLI nightly build and would like to switch to using the package installer, follow these steps.
**To switch from Homebrew to the package installer**
1. Uninstall the Homebrew installed Amazon SAM CLI nightly build.
```
$ brew uninstall aws-sam-cli-nightly
```
1. Verify that the Amazon SAM CLI nightly build is uninstalled by running the following:
```
$ sam-nightly --version
zsh: command not found: sam-nightly
```
1. Follow steps in the previous section to install the Amazon SAM CLI nightly build.
## Installing the Amazon SAM CLI into a virtual environment using pip
We recommend using the native package installer to install the Amazon SAM CLI. If you must use pip, we recommend that you install the Amazon SAM CLI into a virtual environment. This ensures a clean installation environment and an isolated environment if errors occur.
**Note**
As of October 24, 2023, the Amazon SAM CLI is discontinuing support for Python 3.7. To learn more, see [Amazon SAM CLI discontinuing support for Python 3.7](important-notes.md#important-notes-2023-10-python).
**To install the Amazon SAM CLI into a virtual environment**
1. From a starting directory of your choice, create a virtual environment and name it.
------
#### [ Linux / macOS ]
```
$ mkdir project
$ cd project
$ python3 -m venv venv
```
------
#### [ Windows ]
```
> mkdir project
> cd project
> py -3 -m venv venv
```
------
1. Activate the virtual environment
------
#### [ Linux / macOS ]
```
$ . venv/bin/activate
```
The prompt changes to show you that your virtual environment is active.
```
(venv) $
```
------
#### [ Windows ]
```
> venv\Scripts\activate
```
The prompt changes to show you that your virtual environment is active.
```
(venv) >
```
------
1. Install the Amazon SAM CLI into your virtual environment.
```
(venv) $ pip install --upgrade aws-sam-cli
```
1. Verify that the Amazon SAM CLI is installed correctly.
```
(venv) $ sam --version
SAM CLI, version 1.94.0
```
1. You can use the `deactivate` command to exit the virtual environment. Whenever you start a new session, you must reactivate the environment.
## Managing the Amazon SAM CLI with Homebrew
**Note**
Starting September 2023, Amazon will no longer maintain the Amazon managed Homebrew installer for the Amazon SAM CLI (`aws/tap/aws-sam-cli`). To continue using Homebrew, you can use the community managed installer (`aws-sam-cli`). From September 2023, any Homebrew command that references `aws/tap/aws-sam-cli` will redirect to `aws-sam-cli`.
We recommend that you use our supported [installation](install-sam-cli.md) and [upgrade](#manage-sam-cli-versions-upgrade) methods.
### Installing the Amazon SAM CLI using Homebrew
**Note**
These instructions use the community managed Amazon SAM CLI Homebrew installer. For further support, see the *[homebrew-core](https://github.com/Homebrew/homebrew-core/issues) repository*.
**To install the Amazon SAM CLI**
1. Run the following:
```
$ brew install aws-sam-cli
```
1. Verify the installation:
```
$ sam --version
```
After successful installation of the Amazon SAM CLI, you should see output like the following:
```
SAM CLI, version 1.94.0
```
### Upgrading the Amazon SAM CLI using Homebrew
To upgrade the Amazon SAM CLI using Homebrew, run the following command:
```
$ brew upgrade aws-sam-cli
```
### Uninstalling a Homebrew installed Amazon SAM CLI
If the Amazon SAM CLI was installed using Homebrew, follow these steps to uninstall it.
**To uninstall the Amazon SAM CLI**
1. Run the following:
```
$ brew uninstall aws-sam-cli
```
1. Verify that the Amazon SAM CLI is uninstalled by running the following:
```
$ sam --version
command not found: sam
```
### Switching to the community managed Homebrew installer
If you are using the Amazon managed Homebrew installer (`aws/tap/aws-sam-cli`) and prefer to continue using Homebrew, we recommend switching to the community managed Homebrew installer (`aws-sam-cli`).
To switch in a single command, run the following:
```
$ brew uninstall aws-sam-cli && brew untap aws/tap && brew cleanup aws/tap && brew update && brew install aws-sam-cli
```
Follow these instructions to run each command individually.
**To switch to the community managed Homebrew installer**
1. Uninstall the Amazon managed Homebrew version of the Amazon SAM CLI:
```
$ brew uninstall aws-sam-cli
```
1. Verify that the Amazon SAM CLI has been uninstalled:
```
$ which sam
sam not found
```
1. Remove the Amazon managed Amazon SAM CLI tap:
```
$ brew untap aws/tap
```
If you receive an error like the following, add the `--force` option and try again.
```
Error: Refusing to untap aws/tap because it contains the following installed formulae or casks:
aws-sam-cli-nightly
```
1. Remove cached files for the Amazon managed installer:
```
$ brew cleanup aws/tap
```
1. Update Homebrew and all formulae:
```
$ brew update
```
1. Install the community managed version of the Amazon SAM CLI:
```
$ brew install aws-sam-cli
```
1. Verify that the Amazon SAM CLI is successfully installed:
```
$ sam --version
SAM CLI, version 1.94.0
```
## Troubleshooting
If you come across errors when installing or using the Amazon SAM CLI, see [Amazon SAM CLI troubleshooting](sam-cli-troubleshooting.md).