Implementation:Ggml org Llama cpp GGUF Split

Knowledge Sources	Ggml_org_Llama_cpp
Domains	GGUF, Model_Management
Last Updated	2026-02-15 00:00 GMT

Overview

CLI tool to split a single GGUF file into multiple shards or merge multiple shards back into one.

Description

This standalone executable parses split parameters (operation mode, max tensors or max size per shard) and performs either split or merge operations. For splitting, it uses a `split_strategy` to determine how tensors are distributed across output files, then writes each shard with proper GGUF metadata (including split count, index, and tensor ranges). For merging, it reads multiple numbered shard files, combines their tensors and metadata into a single output GGUF. It supports a `--no-tensor-first-split` option to keep the first shard metadata-only, and a `--dry-run` mode to preview the split plan without writing files.

Usage

Use this tool when you need to manage large model files that exceed filesystem or transfer size limits. It enables sharding models for distribution and re-merging them for inference use.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: tools/gguf-split/gguf-split.cpp
• Lines: 1-583

Signature

enum split_operation : uint8_t { OP_NONE, OP_SPLIT, OP_MERGE };
enum split_mode : uint8_t { MODE_NONE, MODE_TENSOR, MODE_SIZE };

struct split_params {
    split_operation operation = OP_NONE;
    split_mode mode = MODE_NONE;
    size_t n_bytes_split = 0;
    int n_split_tensors = 128;
    std::string input;
    std::string output;
    bool no_tensor_first_split = false;
    bool dry_run = false;
};

static void split_print_usage(const char * executable);
static size_t split_str_to_n_bytes(std::string str);

// Main entry point
int main(int argc, const char ** argv);

Import

#include "ggml.h"
#include "gguf.h"
#include "llama.h"
#include "common.h"
#include <algorithm>
#include <cinttypes>
#include <climits>
#include <cstdio>
#include <cstdlib>
#include <stdexcept>
#include <cstring>
#include <fstream>
#include <string>
#include <vector>

I/O Contract

Inputs

Name	Type	Required	Description
GGUF_IN	file path (CLI arg)	Yes	Input GGUF file path (single file for split, first shard for merge)
GGUF_OUT	file path (CLI arg)	Yes	Output GGUF file path (base name for split shards, single file for merge)
--split	flag	No	Enable split operation (default)
--merge	flag	No	Enable merge operation
--split-max-tensors	int	No	Maximum tensors per shard (default: 128)
--split-max-size	string	No	Maximum size per shard (e.g., "4G", "128M")
--no-tensor-first-split	flag	No	Keep first shard metadata-only
--dry-run	flag	No	Preview split plan without writing files

Outputs

Name	Type	Description
shard files	GGUF files	Multiple numbered GGUF shard files (for split operation)
merged file	GGUF file	Single combined GGUF file (for merge operation)
dry-run report	stdout	Split plan summary showing tensor distribution across shards

Usage Examples

// Split a large model into shards of max 4GB each
// $ gguf-split --split --split-max-size 4G model.gguf model-split.gguf

// Split by max tensors per shard
// $ gguf-split --split --split-max-tensors 64 model.gguf model-split.gguf

// Merge shards back into a single file
// $ gguf-split --merge model-split-00001-of-00003.gguf model-merged.gguf

// Preview split plan without writing
// $ gguf-split --split --split-max-size 2G --dry-run model.gguf model-split.gguf

// Keep first shard metadata-only
// $ gguf-split --split --split-max-size 4G --no-tensor-first-split model.gguf model-split.gguf

Related Pages

• Principle:Ggml_org_Llama_cpp_GGUFFormat