How to Install the Soup CLI for LLM Fine-Tuning

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 and configuration validated through Pydantic schemas in 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.

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.

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

# 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:

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 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:

# 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:

# 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, which dispatches commands to appropriate sub-modules.
• Configuration validation relies on Pydantic v2 schemas defined in 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}