ztensor 1.2.3

Unified, zero-copy, and safe I/O for deep learning formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

---
sidebar_position: 5
---

# CLI Reference

The `ztensor` CLI inspects, converts, and manipulates tensor files.

## Installation

```bash
cargo install ztensor-cli
```

## Commands

### `convert` - Convert formats

Converts one or more tensor files to a single `.zt` file, detecting the input format by extension.

**Supported input formats:** SafeTensors (`.safetensors`), GGUF (`.gguf`), PyTorch/Pickle (`.pt`, `.bin`, `.pth`, `.pkl`), NumPy (`.npz`), ONNX (`.onnx`), HDF5 (`.h5`, `.hdf5`)

```bash
# Basic conversion
ztensor convert model.safetensors -o model.zt

# With compression
ztensor convert model.gguf -o model.zt -c

# Specific compression level (1-22)
ztensor convert model.safetensors -o model.zt -l 10

# With checksum (none, crc32c, sha256)
ztensor convert model.npz -o model.zt --checksum crc32c

# Multiple input files
ztensor convert part1.safetensors part2.safetensors -o model.zt

# Delete originals after conversion
ztensor convert --delete-original *.safetensors -o model.zt
```

### `info` - Inspect metadata

Prints tensor names, shapes, dtypes, and file properties for any supported format.

```bash
ztensor info model.zt
ztensor info model.safetensors
ztensor info model.gguf
ztensor info weights.npz
```

### `compress` - Compress files

Compresses an existing raw zTensor file with zstd.

```bash
# Default level (3)
ztensor compress raw.zt -o compressed.zt

# Specific level (1-22)
ztensor compress raw.zt -o compressed.zt -l 19
```

### `decompress` - Decompress files

```bash
ztensor decompress compressed.zt -o raw.zt
```

### `merge` - Merge files

Combines multiple zTensor files into one.

```bash
ztensor merge part1.zt part2.zt -o merged.zt
```

### `migrate` - Migrate legacy files

Converts legacy v0.1.0 files to the current v1.2.0 format.

```bash
ztensor migrate old_model.zt -o new_model.zt
```

### `append` - Append tensors

Appends all tensors from a source `.zt` file into an existing target `.zt` file. The target file is modified in-place. Compression and checksum settings from the source are preserved.

```bash
ztensor append model.zt --from extra_weights.zt
```

Errors if any tensor name in the source already exists in the target.

### `remove` - Remove tensors

Removes one or more tensors by name from a `.zt` file, writing the result to a new file.

```bash
ztensor remove model.zt unused_layer old_bias -o trimmed.zt
```

Errors if any specified name is not found in the input.

### `download-hf` - Download from HuggingFace

Downloads safetensors from HuggingFace Hub and converts to zTensor.

```bash
ztensor download-hf microsoft/resnet-18 -o ./models
ztensor download-hf openai-community/gpt2 -o ./models -c
ztensor download-hf openai-community/gpt2 -o ./models -c -l 10
ztensor download-hf private/model -o ./models --token hf_xxxxx
```