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

> Discover Soup CLI system requirements including Python 3.10+ GPU VRAM needs for fine-tuning or CPU inference. Optimize your AI workflow now.

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

---

**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`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/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:

```bash
pipx install soup-cli

```

This installs the CLI and core utilities without pulling in the full training stack. The [`pyproject.toml`](https://github.com/MakazhanAlpamys/Soup/blob/main/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:

```bash
pipx install "soup-cli[train]"

```

This command pulls the optional dependency group defined in [`pyproject.toml`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/doctor.py):

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

```bash
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`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/docs/models.md) in the repository.

### What dependencies are installed with the `[train]` extra?

The [`pyproject.toml`](https://github.com/MakazhanAlpamys/Soup/blob/main/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.