Managing Amazon SAM CLI versions - Amazon Serverless Application Model
Upgrading the Amazon SAM CLIUninstalling the Amazon SAM CLISwitch from HomebrewManaging the Amazon SAM CLI nightly buildInstalling the Amazon SAM CLI into a virtual environment using pipManaging the Amazon SAM CLI with HomebrewTroubleshooting
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

Upgrading the Amazon SAM CLI

To upgrade the Amazon SAM CLI on Linux, follow the installation instructions in Installing the Amazon SAM CLI, but add the --update option to the install command, as follows:

sudo ./sam-installation/install --update

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.

To upgrade the Amazon SAM CLI, repeat the Windows installation steps in Install the Amazon SAM CLI again.

Uninstalling the Amazon SAM CLI

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

  2. Delete the symlink.

    sudo rm /usr/local/bin/sam

  3. Delete the installation directory.

    sudo rm -rf /usr/local/aws-sam-cli

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.

    2. /path-to – Path to where you installed the Amazon SAM CLI program. The default location is /usr/local.

  2. 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.

    2. path-to-symlink-directory – Your $PATH environment variable. The default location is /usr/local/bin.

  3. Verify that the Amazon SAM CLI is uninstalled by running the following: 

    $ sam --version
command not found: sam

To uninstall the Amazon SAM CLI using Windows Settings, follow these steps:

  1. From the Start menu, search for "Add or remove programs".

  2. Choose the result named Amazon SAM Command Line Interface, and then choose Uninstall to launch the uninstaller.

  3. 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 to uninstall the Homebrew managed version.

  2. Follow instructions at Install the Amazon SAM CLI 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.

You can install the nightly build version of the Amazon SAM CLI on the Linux x86_64 platform using the package installer.

To install the Amazon SAM CLI nightly build

  1. Download the package installer from sam-cli-nightly in the aws-sam-cli GitHub repository.

  2. Follow the steps for installing the Amazon SAM CLI to install the nightly build package.

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 in the aws-sam-cli GitHub repository.

  2. Follow the steps for installing the Amazon SAM CLI to install the nightly build package.

The nightly build version of the Amazon SAM CLI is available with this download link: Amazon SAM CLI nightly build. To install the nightly build on Windows, perform the same steps as in the Install the Amazon SAM CLI, 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<YYYYMMDDHHmm>, 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

  2. Verify that the Amazon SAM CLI nightly build is uninstalled by running the following:

    $ sam-nightly --version
zsh: command not found: sam-nightly

  3. 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.

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

  2. 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) >

  3. Install the Amazon SAM CLI into your virtual environment.

    (venv) $ pip install --upgrade aws-sam-cli

  4. Verify that the Amazon SAM CLI is installed correctly.

    (venv) $ sam --version
SAM CLI, version 1.94.0

  5. 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 and 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 repository.

To install the Amazon SAM CLI

  1. Run the following:

    $ brew install aws-sam-cli

  2. 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

  2. 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

  2. Verify that the Amazon SAM CLI has been uninstalled:

    $ which sam
sam not found

  3. 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

  4. Remove cached files for the Amazon managed installer:

    $ brew cleanup aws/tap

  5. Update Homebrew and all formulae:

    $ brew update

  6. Install the community managed version of the Amazon SAM CLI:

    $ brew install aws-sam-cli

  7. 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.