Installation

There are two ways to install XPK:

1. Via pip (Recommended for usage)
2. From Source (Recommended for development)

1. Prerequisites

Ensure the following tools are installed and configured before proceeding.

Core Tools

• Python 3.10+: Ensure pip and venv are included.
  • Check: python3 --version
• Google Cloud SDK (gcloud): Install from here.
  • Run gcloud init
  • Authenticate to Google Cloud.
  • Check: gcloud auth list
  • Run gcloud auth configure-docker to enable image uploads to the registry.

Method-Specific Requirements

Depending on your chosen installation method, you may need these additional tools:

Install Method	Tool	Notes
Source	git	Install via your package manager (e.g., sudo apt-get install git on Debian/Ubuntu)
Source	make	Install via your package manager (e.g., sudo apt-get install make on Debian/Ubuntu)

---

2. Environment Setup (Virtual Environment)

To avoid conflicts with system packages (and the common "This environment is externally managed" error), we strongly recommend installing XPK in a virtual environment.

Run the following to create and activate your environment:

# 1. Create the virtual environment (one-time setup)
VENV_DIR=~/venvp3
python3 -m venv $VENV_DIR

# 2. Activate the environment
# (You must run this command every time you open a new terminal to use xpk)
source $VENV_DIR/bin/activate

---

3. Install XPK

Choose one of the following methods.

Option A: Install via pip

Once your prerequisites are met and your virtual environment is active:

pip install xpk

Option B: Install from Source

If you need to modify the source code or use the latest unreleased features:

# 1. Clone the XPK repository
git clone https://github.com/AI-Hypercomputer/xpk.git
cd xpk

# 2. Install dependencies and build
make install

# 3. Update your PATH
export PATH=$PATH:$PWD/bin

Note: Installing from source is recommended only for contributors and advanced users. Most users should install via PIP for the best stability.

Persisting the PATH configuration when installing from source: To use xpk in future terminal sessions without re-running the export command, add the binary path to your shell configuration:

• For Bash (Linux default):

  echo "export PATH=\$PATH:$PWD/bin" >> ~/.bashrc
  source ~/.bashrc
  

• For Zsh (macOS default):

  echo "export PATH=\$PATH:$PWD/bin" >> ~/.zshrc
  source ~/.zshrc
  

---

4. Verify Installation

Run the following command to ensure XPK is correctly installed and reachable:

xpk --help

If the installation was successful, you will see the help menu listing available commands.

---

5. Post-Installation (Optional)

Enable Bash Completion

To enable tab completion for XPK commands:

1. Install argcomplete:

   pip install argcomplete
   activate-global-python-argcomplete
   

2. Configure XPK completion:

   eval "$(register-python-argcomplete xpk)"
   

---

6. Updating XPK

To get the latest version of XPK:

Via Pip:

pip install --upgrade xpk

From Source: Navigate to your cloned directory and run:

git pull
make install

---

7. Troubleshooting

Issue: command not found: xpk

• Cause: The installation directory is not in your system $PATH.
• Fix: Ensure you have activated your virtual environment. If installing from source, ensure you added the /bin folder to your PATH as described in Section 3.

Issue: error: externally-managed-environment

• Cause: You are trying to install Python packages globally, which is restricted by newer OS versions.
• Fix: Ensure you create and activate a Virtual Environment (see Section 2: Environment Setup).