Skip to content

installation.md

Latest commit

 

History

History
168 lines (117 loc) · 4.55 KB

installation.md

File metadata and controls

168 lines (117 loc) · 4.55 KB

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