Soup CLI System Requirements: Python Version, GPU, and VRAM Specifications

Soup CLI requires Python 3.10, 3.11, or 3.12, runs on Linux/macOS/Windows, and needs at least 8 GB of VRAM for fine-tuning 7B parameter models with QLoRA, though a CPU-only mode is available for inference-only workflows.

Soup CLI is a Python-based command-line tool for fine-tuning large language models hosted in the MakazhanAlpamys/Soup repository. Understanding the Soup CLI system requirements ensures you can successfully execute training jobs or use the lightweight inference mode without encountering compatibility errors deep in the execution pipeline. The tool validates environment prerequisites early to prevent obscure crashes during training.

Python Version Requirements

You must use Python 3.10, 3.11, or 3.12 to run Soup CLI. These specific versions are actively tested in the project's CI pipeline and are the only officially supported interpreter versions. Python 3.13 and newer releases are not yet supported because the underlying PyTorch stack has not been validated for compatibility with them.

The repository's README.md documents these constraints in the Requirements section, where the maintainers explicitly note that versions exceeding 3.12 will cause dependency resolution failures. When you launch the CLI, it performs an early validation check against these version constraints before attempting to import heavy machine learning libraries.

Hardware Requirements for Soup CLI

GPU and Accelerator Support

A CUDA-enabled GPU is strongly recommended for production training workflows. The CLI also supports Apple Silicon (MPS) backends for macOS users, and provides a CPU-only mode for systems without discrete graphics. However, CPU-only operation is significantly slower and intended primarily for development, testing, or inference tasks rather than full fine-tuning jobs.

The hardware detection logic resides in src/soup_cli/doctor.py, which probes for available accelerators at runtime. The CLI configures the training pipeline automatically based on detected hardware, falling back to CPU execution only when no GPU is available.

VRAM Specifications

You need at least 8 GB of VRAM to fine-tune a 7B parameter model using QLoRA quantization. Larger models require proportionally more memory; consult the VRAM guide in docs/models.md for detailed specifications regarding 13B, 70B, and other model sizes. The soup doctor command reports available VRAM before training begins, aborting with a clear error message if your GPU lacks sufficient memory for the selected model configuration.

Installation Options Based on System Capabilities

Soup CLI uses a lazy-import architecture that keeps the core installation lightweight. Heavy dependencies such as torch, transformers, peft, and trl are only loaded when specific commands require them.

Minimal Installation (No GPU Required)

Install the light core if you only need configuration management, data preprocessing, or inference on CPU:

pipx install soup-cli

This installs the CLI and core utilities without pulling in the full training stack. The pyproject.toml defines this as the base package, allowing the tool to run on any system meeting the Python version requirement.

Full Training Stack (GPU Recommended)

Install the complete training dependencies if your system has a CUDA GPU or Apple Silicon with adequate VRAM:

pipx install "soup-cli[train]"

This command pulls the optional dependency group defined in pyproject.toml under [project.optional-dependencies], installing the GPU-enabled PyTorch wheels and related libraries required for soup train and related commands.

Verifying Your Environment with soup doctor

Before starting a training job, verify that your system meets all Soup CLI system requirements by running the diagnostic command implemented in src/soup_cli/doctor.py:

soup doctor

This outputs the detected Python version, CUDA toolkit version, GPU model, and available VRAM. To perform a quick manual check for CUDA availability before installation, run:

python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

If this prints True, your environment satisfies the basic CUDA requirement. The CLI performs this same check internally when initializing training backends, as documented in docs/backends-and-ops.md.

Summary

• Python 3.10–3.12 is strictly required; Python 3.13+ is unsupported due to PyTorch compatibility
• 8 GB VRAM is the minimum for fine-tuning 7B models with QLoRA
• CUDA GPU is recommended; MPS and CPU fallback modes are available but slower
• Run soup doctor to validate your environment before training
• Install the [train] extra only when you have adequate GPU resources

Frequently Asked Questions

Can I run Soup CLI without a GPU?

Yes, but only for the light core functionality or very slow CPU inference. The base installation (pipx install soup-cli) works on any machine meeting the Python version requirement. However, training commands require a GPU with sufficient VRAM; CPU-only training is supported technically but executes too slowly for practical use.

Why does Soup CLI require Python 3.10–3.12 specifically?

These versions match the current PyTorch ecosystem validation. According to the README.md Requirements section, Python 3.13 and newer are not yet supported because the PyTorch stack has not been validated for them, and attempting to install on newer versions will result in dependency resolution failures.

How do I check if my system meets the VRAM requirements?

Execute soup doctor to display your GPU model and available VRAM. For detailed calculations regarding model size, batch size, and quantization method, refer to the VRAM guide located at docs/models.md in the repository.

What dependencies are installed with the [train] extra?

The pyproject.toml defines this extra group to include torch, transformers, peft, and trl. These dependencies utilize a lazy-import design, meaning they only load into memory when you execute training-specific commands, keeping the CLI startup time fast even after installing the full stack.

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