# How to Install the Soup CLI for LLM Fine-Tuning

> Install the Soup CLI for LLM fine-tuning using pip or pipx. Learn how to add optional dependencies for a streamlined setup and begin training your models efficiently.

- Repository: [Alpamys Makazhan/Soup](https://github.com/MakazhanAlpamys/Soup)
- Tags: how-to-guide
- Published: 2026-09-06

---

**The Soup CLI is installed via `pip` or `pipx` using optional dependency extras (e.g., `"soup-cli[train]"`, `"soup-cli[all]"`) to maintain a lightweight core, with the entry point defined in [`src/soup_cli/__main__.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/__main__.py) and configuration validated through Pydantic schemas in [`src/soup_cli/config/schema.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/config/schema.py).**

The Soup CLI is a Python-based command-line tool designed to streamline large language model (LLM) fine-tuning, inference, and deployment. Hosted in the `MakazhanAlpamys/Soup` repository, it employs a modular architecture that separates the lightweight core from heavy dependencies like PyTorch and Transformers. This guide covers how to install the Soup CLI using the documented methods while leveraging the extras matrix defined in [`docs/models.md`](https://github.com/MakazhanAlpamys/Soup/blob/main/docs/models.md).

## Installation Methods

### Install with pipx (Recommended)

Installing via **pipx** isolates the CLI in its own virtual environment, preventing dependency conflicts with other Python projects. This is the preferred method for system-wide CLI accessibility.

```bash

# Install the lightweight core only

pipx install soup-cli

# Install with training dependencies (PyTorch, Transformers, PEFT)

pipx install "soup-cli[train]"

# Install everything (training, serving, UI, optimization backends)

pipx install "soup-cli[all]"

```

Always use **double quotes** around the extra specification (`"soup-cli[train]"`) to ensure compatibility across Bash, Zsh, PowerShell, and CMD.

### Install with pip

Use **pip** when you need to import `soup_cli` as a library within an existing Python environment, such as a Conda environment, virtualenv, or Docker container.

```bash

# Within an activated virtual environment

pip install "soup-cli[train]"

# Or install specific extras for Apple Silicon

pip install "soup-cli[mlx]"

```

### Install from GitHub Source

To access unreleased features or contribute to the project, install directly from the source repository:

```bash
pipx install "git+https://github.com/MakazhanAlpamys/Soup.git"

# Or with extras

pip install "git+https://github.com/MakazhanAlpamys/Soup.git#egg=soup-cli[all]"

```

## Understanding the Extras System

The CLI is deliberately split into a lightweight core (`soup-cli`) and optional extras to avoid pulling in unnecessary dependencies. The base installation contains only the CLI framework, configuration system, and data utilities—it does **not** include PyTorch or training libraries.

Key extras documented in [`docs/models.md`](https://github.com/MakazhanAlpamys/Soup/blob/main/docs/models.md) include:

- **`[train]`** – Core training stack (PyTorch, Transformers, PEFT, Datasets)
- **`[serve]`** – FastAPI server for OpenAI-compatible inference endpoints
- **`[fast]`** – Unsloth backend for 2-5x faster training
- **`[mlx]`** – Apple Silicon optimization via Apple's MLX framework
- **`[sglang]`** – SGLang backend for high-throughput serving
- **`[all]`** – Complete bundle including training, serving, UI, and all optimization backends

## Verifying Your Installation

After installation, validate that the CLI is properly configured and detectable:

```bash

# Display installed version

soup version

# Check GPU availability, dependency versions, and environment health

soup doctor

```

The `soup doctor` command analyzes your system for CUDA/ROm compatibility, verifying that heavy dependencies like PyTorch can access your hardware acceleration.

## Quick Start: From Install to Fine-Tuning

Follow this complete workflow to verify installation and begin fine-tuning:

```bash

# 1. Install CLI with training capabilities

pipx install "soup-cli[train]"

# 2. Initialize a new chat-bot project template

soup init --template chat

# 3. Train using LoRA/QLoRA (configured in soup.yaml)

soup train --config soup.yaml

# 4. Serve the fine-tuned model via OpenAI-compatible API

soup serve --model ./output

```

## Summary

- The Soup CLI entry point is located in [`src/soup_cli/__main__.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/__main__.py), which dispatches commands to appropriate sub-modules.
- Configuration validation relies on Pydantic v2 schemas defined in [`src/soup_cli/config/schema.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/config/schema.py).
- Use **pipx** for isolated, system-wide installation and **pip** when integrating `soup_cli` as a library dependency.
- Always wrap extra specifications in double quotes (e.g., `"soup-cli[train]"`) to prevent shell interpretation errors.
- The base `soup-cli` package is lightweight; you must install extras like `[train]` or `[all]` to access PyTorch and training functionality.

## Frequently Asked Questions

### Why does the base `soup-cli` package not include PyTorch?

The base package intentionally excludes heavy ML frameworks to keep installation fast and dependency conflicts minimal. As implemented in [`src/soup_cli/config/schema.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/config/schema.py), the configuration system validates dependencies dynamically, allowing you to install only the extras required for your specific hardware and use case (training, serving, or Apple Silicon inference).

### How do I install Soup CLI for Apple Silicon Macs?

Install the `[mlx]` extra to leverage Apple's MLX framework for optimized local inference. Use the command `pipx install "soup-cli[mlx]"` or `pip install "soup-cli[mlx]"` depending on your environment preference. This pulls in the MLX-specific backends without installing CUDA-dependent PyTorch binaries.

### What is the difference between `[train]` and `[all]` extras?

The `[train]` extra installs the core fine-tuning stack (PyTorch, Transformers, PEFT, and Datasets), while `[all]` bundles everything including serving dependencies (FastAPI), UI components, optimization backends like Unsloth (`[fast]`), and specialized inference engines. Use `[train]` for dedicated training workflows and `[all]` for full-stack development or Docker deployments.