> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Set up AI Training on your system

# Installing AI Training

This guide will walk you through installing AI Training on your computer. The process takes about 5-10 minutes.

## What You'll Get

When you install AI Training with `pip` or `uv`, you get:

* **Command Line Interface** - The `aitraining` command for training models
* **Chat Interface** - Test and interact with your trained models via browser
* **Python API** - Import and use in your Python scripts

All interfaces are included in a single package installation.

## Prerequisites

Before installing AI Training, you need Python on your system. Python is a programming language that AI Training runs on.

### Check if Python is Installed

Open your terminal (Mac) or Command Prompt (Windows) and type:

```bash theme={null}
python --version
```

If you see a version number like `Python 3.8.0` or higher, you're good to go. AI Training requires Python 3.8 or newer (3.10+ recommended).

If you get an error or have an older version, follow the installation steps below.

## Installing Python

<Tabs>
  <Tab title="Windows">
    ### Windows Installation

    1. **Download Python**
       * Go to [python.org/downloads](https://www.python.org/downloads/)
       * Click the yellow "Download Python" button
       * Save the installer

    2. **Run the Installer**
       * Double-click the downloaded file
       * **Important**: Check "Add Python to PATH" at the bottom
       * Click "Install Now"
       * Wait for installation to complete

    3. **Verify Installation**
       * Open Command Prompt (search for "cmd" in Start menu)
       * Type: `python --version`
       * You should see the Python version

    4. **Install pip (if needed)**
       * pip usually comes with Python, but verify:
       ```bash theme={null}
       pip --version
       ```
       * If not found, run:
       ```bash theme={null}
       python -m ensurepip --upgrade
       ```
  </Tab>

  <Tab title="Mac">
    ### Mac Installation

    1. **Using Homebrew (Recommended)**

       If you don't have Homebrew, install it first:

       ```bash theme={null}
       /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
       ```

       Then install Python:

       ```bash theme={null}
       brew install python@3.11
       ```

    2. **Alternative: Direct Download**
       * Go to [python.org/downloads](https://www.python.org/downloads/)
       * Download the macOS installer
       * Run the installer

    3. **Verify Installation**
       * Open Terminal (find it in Applications > Utilities)
       * Type: `python3 --version`
       * You should see the Python version

    4. **Install pip (if needed)**
       * pip usually comes with Python, but verify:
       ```bash theme={null}
       pip3 --version
       ```
  </Tab>

  <Tab title="Linux">
    ### Linux Installation

    Most Linux distributions come with Python. If not:

    **Ubuntu/Debian:**

    ```bash theme={null}
    sudo apt update
    sudo apt install python3 python3-pip
    ```

    **Fedora:**

    ```bash theme={null}
    sudo dnf install python3 python3-pip
    ```

    **Arch:**

    ```bash theme={null}
    sudo pacman -S python python-pip
    ```
  </Tab>
</Tabs>

## Installing AI Training

Once Python is ready, you have two options for installing AI Training. We recommend using `uv` for faster installation.

### Option 1: Using uv (Recommended)

uv is a modern Python package installer that's much faster than pip and handles virtual environments automatically.

#### Install uv first:

<Tabs>
  <Tab title="Windows">
    ```bash theme={null}
    # Using PowerShell (as administrator)
    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```
  </Tab>

  <Tab title="Mac/Linux">
    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Tab>
</Tabs>

#### Then install AI Training:

```bash theme={null}
# uv automatically creates and manages a virtual environment
uv pip install aitraining
```

That's it! uv handles the virtual environment for you automatically.

### Option 2: Using pip (Traditional method)

If you prefer the traditional approach or can't install uv:

#### Step 1: Create a Virtual Environment

A virtual environment keeps AI Training's files separate from other Python projects.

<Tabs>
  <Tab title="Windows">
    ```bash theme={null}
    python -m venv aitraining-env
    aitraining-env\Scripts\activate
    ```
  </Tab>

  <Tab title="Mac/Linux">
    ```bash theme={null}
    python3 -m venv aitraining-env
    source aitraining-env/bin/activate
    ```
  </Tab>
</Tabs>

You'll see `(aitraining-env)` in your terminal when the environment is active.

#### Step 2: Install AI Training

```bash theme={null}
pip install aitraining
```

This downloads and installs AI Training from PyPI with all its dependencies (including PyTorch).

### Step 3: Verify Installation

Check that everything installed correctly:

```bash theme={null}
aitraining --version
```

You should see the AI Training version number.

## Choose Your Interface

AI Training offers three ways to work:

<CardGroup cols={3}>
  <Card title="Command Line" icon="terminal" href="/cli/installation-setup">
    **Best for training**

    Train models with commands. Good for scripts and automation.

    Start with: `aitraining --help`
  </Card>

  <Card title="Chat Interface" icon="message" href="/chat/launching">
    **Best for testing**

    Test your trained models interactively in a browser.

    Start with: `aitraining chat`
  </Card>

  <Card title="Python API" icon="code" href="/api/introduction">
    **Best for developers**

    Integrate training into your Python applications.

    Start with: `from autotrain.trainers.clm.params import LLMTrainingParams`
  </Card>
</CardGroup>

## Optional Dependencies

Some features require additional packages:

| Feature              | Package        | Install                  | Platform                                    |
| -------------------- | -------------- | ------------------------ | ------------------------------------------- |
| Faster LoRA training | `unsloth`      | `pip install unsloth`    | Linux (SFT only, llama/mistral/gemma/qwen2) |
| Flash Attention 2    | `flash-attn`   | `pip install flash-attn` | Linux (CUDA)                                |
| Distributed training | `accelerate`   | Included                 | Linux/Mac/Windows                           |
| DeepSpeed Zero-3     | `deepspeed`    | `pip install deepspeed`  | Linux                                       |
| 4/8-bit quantization | `bitsandbytes` | Included                 | **Linux only**                              |

<Note>
  **Accelerate is required** for multi-GPU and distributed training. It is included with AITraining. DeepSpeed is optional and provides Zero-3 memory optimization for very large models.
</Note>

<Warning>
  **Quantization (int4/int8) only works on Linux.** The `bitsandbytes` library required for `--quantization int4` or `--quantization int8` is not available on Windows or macOS.
</Warning>

### GPU Setup (Optional)

For NVIDIA GPU training, you may want to reinstall PyTorch with your specific CUDA version:

```bash theme={null}
# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
```

### Weights & Biases Setup (Optional)

AITraining uses W\&B for logging by default. To enable:

```bash theme={null}
pip install wandb
wandb login
```

Or set the environment variable: `WANDB_API_KEY=your_key`

## Common Issues

<AccordionGroup>
  <Accordion title="'python' is not recognized (Windows)">
    Python isn't in your system PATH. Try:

    * Use `python3` instead of `python`
    * Reinstall Python and check "Add Python to PATH"
    * Manually add Python to PATH in System Environment Variables
  </Accordion>

  <Accordion title="Permission denied errors">
    On Mac/Linux, you might need to use `sudo`:

    ```bash theme={null}
    sudo pip install aitraining
    ```

    Or better, use a virtual environment (shown above).
  </Accordion>

  <Accordion title="pip: command not found">
    pip didn't install with Python. Install it:

    ```bash theme={null}
    python -m ensurepip --upgrade
    ```

    Or on Linux:

    ```bash theme={null}
    sudo apt install python3-pip
    ```
  </Accordion>

  <Accordion title="PyTorch installation fails">
    * Make sure you have enough disk space (PyTorch is large)
    * Try upgrading pip first: `pip install --upgrade pip`
    * For GPU support, ensure CUDA drivers are installed
  </Accordion>
</AccordionGroup>

## Next Steps

Installation complete! Now you're ready to train your first model:

<Card title="Quick Start Tutorial" icon="play" href="/foundations/quickstart">
  Train your first AI model in 10 minutes
</Card>

## Need Help?

* Join our [Discord community](https://discord.gg/monostate) for support
* Check [GitHub issues](https://github.com/monostate/aitraining) for known problems
* Email [support@monostate.ai](mailto:support@monostate.ai) for direct help