# Installing AWS ParallelCluster
<a name="install"></a>

AWS ParallelCluster is distributed as a Python package and is installed using `pip`, the Python package manager. For more information on installing Python packages, see [Installing packages](https://packaging.python.org/tutorials/installing-packages/) in the *Python Packaging User Guide*.

**Ways to install AWS ParallelCluster:**
+ [Using a virtual environment (recommended)](#install-tool-venv)
+ [Using `pip`](#install-tool-pip)

You can find the version number of the most recent CLI on the [releases page on GitHub](https://github.com/aws/aws-parallelcluster/releases).

In this guide, the command examples assume that you have Python v3 installed. The `pip` command examples use the `pip3` version.

## Installing AWS ParallelCluster in a virtual environment (recommended)
<a name="install-tool-venv"></a>

We recommend that you install AWS ParallelCluster in a virtual environment. If you encounter issues when you attempt to install AWS ParallelCluster with `pip3`, you can [install AWS ParallelCluster in a virtual environment](install-virtualenv.md) to isolate the tool and its dependencies. Or you can use a different version of Python than you normally do.

## Installing AWS ParallelCluster in a non-virtual environment using pip
<a name="install-tool-pip"></a>

The primary distribution method for AWS ParallelCluster on Linux, Windows, and macOS is `pip`, which is a package manager for Python. It provides a way to install, upgrade, and remove Python packages and their dependencies.

**Current AWS ParallelCluster Version**  
AWS ParallelCluster is updated regularly. To determine whether you have the latest version, see the [releases page on GitHub](https://github.com/aws/aws-parallelcluster/releases).

If you already have `pip` and a supported version of Python, you can install AWS ParallelCluster by using the following command. If you have Python version 3\$1 installed, we recommend that you use the **pip3** command.

```
$ pip3 install "aws-parallelcluster<3.0" --upgrade --user
```

## Steps to take after installation
<a name="install-post"></a>

After you install AWS ParallelCluster, you might need to add the executable file path to your `PATH` variable. For platform-specific instructions, see the following topics:
+ **Linux** – [Add the AWS ParallelCluster executable to your command line path](install-linux.md#install-linux-path)
+ **macOS** – [Add the AWS ParallelCluster executable to your command line path](install-macos.md#install-macos-path)
+ **Windows** – [Add the AWS ParallelCluster executable to your command line path](install-windows.md#install-windows-path)

You can verify that AWS ParallelCluster installed correctly by running `pcluster version`.

```
$ pcluster version
2.11.9
```

AWS ParallelCluster is updated regularly. To update to the latest version of AWS ParallelCluster, run the installation command again. For details about the latest version of AWS ParallelCluster, see the [AWS ParallelCluster release notes](https://github.com/aws/aws-parallelcluster/blob/v2.11.9/CHANGELOG.md).

```
$ pip3 install "aws-parallelcluster<3.0" --upgrade --user
```

To uninstall AWS ParallelCluster, use `pip uninstall`.

```
$ pip3 uninstall "aws-parallelcluster<3.0"
```

If you don't have Python and `pip`, use the procedure for your environment.

## Detailed instructions for each environment
<a name="install-sections"></a>
+ [Install AWS ParallelCluster in a virtual environment (recommended)](install-virtualenv.md)
+ [Install AWS ParallelCluster on Linux](install-linux.md)
+ [Install AWS ParallelCluster on macOS](install-macos.md)
+ [Install AWS ParallelCluster on Windows](install-windows.md)

# Install AWS ParallelCluster in a virtual environment (recommended)
<a name="install-virtualenv"></a>

We recommend that you install AWS ParallelCluster in a virtual environment to avoid requirement version conflicts with other `pip` packages.

**Prerequisites**
+ Verify that `pip` and Python are installed. We recommend `pip3`, and Python 3 version 3.8. If you are using Python 2, use `pip` instead of `pip3` and `virtualenv` instead of `venv`.

**To install AWS ParallelCluster in a virtual environment**

1. If `virtualenv` is not installed, install `virtualenv` using `pip3`. If `python3 -m virtualenv help` displays help information, go to step 2.

------
#### [ Linux, macOS, or Unix ]

   ```
   $ python3 -m pip install --upgrade pip
   $ python3 -m pip install --user --upgrade virtualenv
   ```

   Run `exit` to leave the current terminal window and open a new terminal window to pick up changes to the environment.

------
#### [ Windows ]

   ```
   C:\>pip3 install --user --upgrade virtualenv
   ```

   Run `exit` to leave the current command prompt and open a new command prompt to pick up changes to the environment.

------

1. Create a virtual environment and name it.

------
#### [ Linux, macOS, or Unix ]

   ```
   $ python3 -m virtualenv ~/apc-ve
   ```

   Alternatively, you can use the `-p` option to specify a specific version of Python.

   ```
   $ python3  -m virtualenv -p $(which python3) ~/apc-ve
   ```

------
#### [ Windows ]

   ```
   C:\>virtualenv %USERPROFILE%\apc-ve
   ```

------

1. <a name="activate-virtual-environment"></a>Activate your new virtual environment.

------
#### [ Linux, macOS, or Unix ]

   ```
   $ source ~/apc-ve/bin/activate
   ```

------
#### [ Windows ]

   ```
   C:\>%USERPROFILE%\apc-ve\Scripts\activate
   ```

------

1. Install AWS ParallelCluster into your virtual environment.

------
#### [ Linux, macOS, or Unix ]

   ```
   (apc-ve)~$ python3 -m pip install --upgrade "aws-parallelcluster<3.0"
   ```

------
#### [ Windows ]

   ```
   (apc-ve) C:\>pip3 install --upgrade "aws-parallelcluster<3.0"
   ```

------

1. Verify that AWS ParallelCluster is installed correctly.

------
#### [ Linux, macOS, or Unix ]

   ```
   $ pcluster version
   2.11.9
   ```

------
#### [ Windows ]

   ```
   (apc-ve) C:\>pcluster version
   2.11.9
   ```

------

You can use the `deactivate` command to exit the virtual environment. Each time you start a session, you must [reactivate the environment](#activate-virtual-environment).

To upgrade to the latest version of AWS ParallelCluster, run the installation command again.

------
#### [ Linux, macOS, or Unix ]

```
(apc-ve)~$ python3 -m pip install --upgrade "aws-parallelcluster<3.0"
```

------
#### [ Windows ]

```
(apc-ve) C:\>pip3 install --upgrade "aws-parallelcluster<3.0"
```

------

# Install AWS ParallelCluster on Linux
<a name="install-linux"></a>

You can install AWS ParallelCluster and its dependencies on most Linux distributions by using `pip`, a package manager for Python. First, determine if Python and `pip` are installed:

1. To determine if your version of Linux includes Python and `pip`, run `pip --version`.

   ```
   $ pip --version
   ```

   If you have `pip` installed, go on to the [Install AWS ParallelCluster with pip](install.md) topic. Otherwise, continue with Step 2.

1. To determine if Python is installed, run `python --version`.

   ```
   $ python --version
   ```

   If you have Python 3 version 3.6\$1 or Python 2 version 2.7 installed, go on to the [Install AWS ParallelCluster with pip](install.md) topic. Otherwise, [install Python](install-linux-python.md), and then return to this procedure to install `pip`.

1. Install `pip` by using the script that the *Python Packaging Authority* provides. 

1. Use the `curl` command to download the installation script.

   ```
   $ curl -O https://bootstrap.pypa.io/get-pip.py
   ```

1. Run the script with Python to download and install the latest version of `pip` and other required support packages.

   ```
   $ python get-pip.py --user
   ```

   or

   ```
   $ python3 get-pip.py --user
   ```

   When you include the `--user` switch, the script installs `pip` to the path `~/.local/bin`.

1. To verify that the folder that contains `pip` is part of your `PATH` variable, do the following:

   1. Find your shell's profile script in your user folder. If you're not sure which shell you have, run `basename $SHELL`.

      ```
      $ ls -a ~
      .  ..  .bash_logout  .bash_profile  .bashrc  Desktop  Documents  Downloads
      ```
      + **Bash** – `.bash_profile`, `.profile`, or `.bash_login`
      + **Zsh** – `.zshrc`
      + **Tcsh** – `.tcshrc`, `.cshrc` or `.login`

   1. Add an export command at the end of your profile script that's similar to the following example.

      ```
      export PATH=~/.local/bin:$PATH
      ```

      The export command inserts the path, which is `~/.local/bin` in this example, at the front of the existing `PATH` variable.

   1. To put these changes into effect, reload the profile into your current session.

      ```
      $ source ~/.bash_profile
      ```

1. Verify that `pip` is installed correctly.

   ```
   $ pip3 --version
   pip 21.3.1 from ~/.local/lib/python3.6/site-packages (python 3.6)
   ```

**Topics**
+ [

## Install AWS ParallelCluster with `pip`
](#install-linux-with-pip)
+ [

## Add the AWS ParallelCluster executable to your command line path
](#install-linux-path)
+ [

# Installing Python on Linux
](install-linux-python.md)

## Install AWS ParallelCluster with `pip`
<a name="install-linux-with-pip"></a>

Use `pip` to install AWS ParallelCluster.

```
$ python3 -m pip install "aws-parallelcluster<3.0" --upgrade --user
```

When you use the `--user` switch, `pip` installs AWS ParallelCluster to `~/.local/bin`. 

Verify that AWS ParallelCluster installed correctly.

```
$ pcluster version
2.11.9
```

To upgrade to the latest version, run the installation command again.

```
$ python3 -m pip install "aws-parallelcluster<3.0" --upgrade --user
```

## Add the AWS ParallelCluster executable to your command line path
<a name="install-linux-path"></a>

After installing with `pip`, you might need to add the `pcluster` executable to your operating system's `PATH` environment variable.

To verify the folder in which `pip` installed AWS ParallelCluster, run the following command.

```
$ which pcluster
/home/username/.local/bin/pcluster
```

If you omitted the `--user` switch when you installed AWS ParallelCluster, the executable might be in the `bin` folder of your Python installation. If you don't know where Python is installed, run this command.

```
$ which python
/usr/local/bin/python
```

Note that the output might be the path to a symlink, not to the actual executable. To see where the symlink points, run `ls -al`.

```
$ ls -al $(which python)
/usr/local/bin/python -> ~/.local/Python/3.6/bin/python3.6
```

If this is the same folder that you added to the path in step 3 in [Installing AWS ParallelCluster](install.md), you're done with the installation. Otherwise, you must perform steps 3a – 3c again, adding this additional folder to the path.

# Installing Python on Linux
<a name="install-linux-python"></a>

If your distribution didn't come with Python, or came with an earlier version, install Python before installing `pip` and AWS ParallelCluster.

**To install Python 3 on Linux**

1. Check to see if Python is already installed.

   ```
   $ python3 --version
   ```

   or

   ```
   $ python --version
   ```
**Note**  
If your Linux distribution came with Python, you might need to install the Python developer package. The developer package includes the headers and libraries that are required to compile extensions and to install AWS ParallelCluster. Use your package manager to install the developer package. It is typically named `python-dev` or `python-devel`.

1. If Python 2.7 or later is not installed, install Python with your distribution's package manager. The command and package name varies:
   + On Debian derivatives such as Ubuntu, use `apt`.

     ```
     $ sudo apt-get install python3
     ```
   + On Red Hat and derivatives, use `yum`.

     ```
     $ sudo yum install python3
     ```
   + On SUSE and derivatives, use `zypper`.

     ```
     $ sudo zypper install python3
     ```

1. To verify that Python installed correctly, open a command prompt or shell and run the following command.

   ```
   $ python3 --version
   Python 3.8.11
   ```

# Install AWS ParallelCluster on macOS
<a name="install-macos"></a>

**Topics**
+ [

## Prerequisites
](#install-bundle-macos-os-prereq)
+ [

## Install AWS ParallelCluster on macOS using pip
](#install-macos-pip)
+ [

## Add the AWS ParallelCluster executable to your command line path
](#install-macos-path)

## Prerequisites
<a name="install-bundle-macos-os-prereq"></a>
+ Python 3 version 3.7\$1 or Python 2 version 2.7

Check your Python installation.

```
$ python --version
```

If your computer doesn't already have Python installed, or if you want to install a different version of Python, follow the procedure in [Install AWS ParallelCluster on Linux](install-linux.md).

## Install AWS ParallelCluster on macOS using pip
<a name="install-macos-pip"></a>

You can also use `pip` directly to install AWS ParallelCluster. If you don't have `pip`, follow the instructions in the main [installation topic](install.md). Run `pip3 --version` to see if your version of macOS already includes Python and `pip3`.

```
$ pip3 --version
```

**To install AWS ParallelCluster on macOS**

1. Download and install the latest version of Python from the [downloads page](https://www.python.org/downloads/mac-osx/) of [Python.org](https://www.python.org).

1. Download and run the `pip3` installation script provided by the Python Packaging Authority.

   ```
   $ curl -O https://bootstrap.pypa.io/get-pip.py
   $ python3 get-pip.py --user
   ```

1. Use your newly installed `pip3` to install AWS ParallelCluster. We recommend that if you use Python version 3\$1, you use the `pip3` command.

   ```
   $ python3 -m pip install "aws-parallelcluster<3.0" --upgrade --user
   ```

1. Verify that AWS ParallelCluster is installed correctly.

   ```
   $ pcluster version
   2.11.9
   ```

   If the program isn't found, [add it to your command line path](#install-macos-path).

To upgrade to the latest version, run the installation command again.

```
$ pip3 install "aws-parallelcluster<3.0" --upgrade --user
```

## Add the AWS ParallelCluster executable to your command line path
<a name="install-macos-path"></a>

After installing with `pip`, you might need to add the `pcluster` program to your operating system's `PATH` environment variable. The location of the program depends on where Python is installed.

**Example AWS ParallelCluster install location - macOS with Python 3.6 and `pip` (user mode)**  

```
~/Library/Python/3.6/bin
```
Substitute the version of Python that you have for the version in the preceding example.

If you don't know where Python is installed, run `which python`.

```
$ which python3
/usr/local/bin/python3
```

The output might be the path to a symlink, not the path to the actual program. Run `ls -al` to see where it points.

```
$ ls -al /usr/local/bin/python3
lrwxr-xr-x  1 username  admin  36 Mar 12 12:47 /usr/local/bin/python3 -> ../Cellar/python/3.6.8/bin/python3
```

`pip` installs programs in the same folder that contains the Python application. Add this folder to your `PATH` variable.

**To modify your `PATH` variable (Linux, macOS, or Unix)**

1. Find your shell's profile script in your user folder. If you're not sure which shell you have, run `echo $SHELL`.

   ```
   $ ls -a ~
   .  ..  .bash_logout  .bash_profile  .bashrc  Desktop  Documents  Downloads
   ```
   + **Bash** – `.bash_profile`, `.profile`, or `.bash_login`
   + **Zsh** – `.zshrc`
   + **Tcsh** – `.tcshrc`, `.cshrc`, or `.login`

1. Add an export command to your profile script.

   ```
   export PATH=~/.local/bin:$PATH
   ```

   This command adds a path, `~/.local/bin` in this example, to the current `PATH` variable.

1. Load the profile into your current session.

   ```
   $ source ~/.bash_profile
   ```

# Install AWS ParallelCluster on Windows
<a name="install-windows"></a>

You can install AWS ParallelCluster on Windows by using `pip`, which is a package manager for Python. If you already have `pip`, follow the instructions in the main [installation topic](install.md).

**Topics**
+ [

## Install AWS ParallelCluster using Python and `pip` on Windows
](#install-windows-pip)
+ [

## Add the AWS ParallelCluster executable to your command line path
](#install-windows-path)

## Install AWS ParallelCluster using Python and `pip` on Windows
<a name="install-windows-pip"></a>

The Python Software Foundation provides installers for Windows that include `pip`.

**To install Python and `pip` (Windows)**

1. Download the Python Windows x86-64 installer from the [downloads page](https://www.python.org/downloads/windows/) of [Python.org](https://www.python.org).

1. Run the installer.

1. Choose **Add Python 3 to PATH**.

1. Choose **Install Now**.

The installer installs Python in your user folder and adds its program folders to your user path.

**To install AWS ParallelCluster with `pip3` (Windows)**

If you use Python version 3\$1, we recommend that you use the `pip3` command.

1. Open the **Command Prompt** from the **Start** menu.

1. Use the following commands to verify that Python and `pip` are both installed correctly.

   ```
   C:\>py --version
   Python 3.8.11
   C:\>pip3 --version
   pip 21.3.1 from c:\python38\lib\site-packages\pip (python 3.8)
   ```

1. Install AWS ParallelCluster using `pip`.

   ```
   C:\>pip3 install "aws-parallelcluster<3.0"
   ```

1. Verify that AWS ParallelCluster is installed correctly.

   ```
   C:\>pcluster version
   2.11.9
   ```

To upgrade to the latest version, run the installation command again.

```
C:\>pip3 install --user --upgrade "aws-parallelcluster<3.0"
```

## Add the AWS ParallelCluster executable to your command line path
<a name="install-windows-path"></a>

After installing AWS ParallelCluster with `pip`, add the `pcluster` program to your operating system's `PATH` environment variable.

You can find where the `pcluster` program is installed by running the following command.

```
C:\>where pcluster
C:\Python38\Scripts\pcluster.exe
```

If that command does not return any results, then you must add the path manually. Use the command line or Windows Explorer to discover where it is installed on your computer. Typical paths include:
+ **Python 3 and `pip3`** – `C:\Python38\Scripts\`
+ **Python 3 and `pip3` --user option** – `%APPDATA%\Python\Python38\Scripts`

**Note**  
Folder names that include version numbers can vary. The preceding examples show Python38. Replace as needed with the version number that you are using.

**To modify your PATH variable (Windows)**

1. Press the Windows key and enter **environment variables**.

1. Choose **Edit environment variables for your account**.

1. Choose **PATH**, and then choose **Edit**.

1. Add the path to the **Variable value** field. For example: ***C:\$1new\$1path***

1. Choose **OK** twice to apply the new settings.

1. Close any running command prompts and reopen the command prompt window.