install uv (for macOS or Linux)

curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/FujitsuResearch/OneCompression.git cd OneCompression

The `uv sync` command creates a Python virtual environment and installs all dependent libraries.

#### Linux (CUDA quantization / vLLM)

```bash
uv sync --extra cu128 --extra dev --extra visualize

The --extra cu128 option installs the CUDA-enabled version of PyTorch (along with torchvision from the same CUDA index). Replace cu128 with the appropriate variant for your environment: cpu, cu118, cu121, cu124, cu126, cu128, or cu130. PyTorch will be automatically downloaded by uv, so you do not need to install it beforehand.

macOS (development / MPS inference)

uv sync --extra mps --extra dev --extra visualize

On macOS, use --extra mps only. CUDA extras (cu118–cu130), --extra cpu (Linux-only), and --extra vllm are not supported on macOS. After uv sync, you can run GPTQ quantization and Hugging Face generate() inference on MPS; vLLM serving still requires Linux with an NVIDIA GPU. See the MPS device placement (GPTQ vs QEP) note under macOS (MPS) above for why GPTQ runs on CPU while QEP correction uses MPS.

Adding --extra dev installs development tools (black, pre-commit, pytest, pylint). Adding --extra visualize installs matplotlib for visualization features. Adding --extra distributed installs DeepSpeed for multi-GPU training. Adding --extra hydra installs hydra-core for the example scripts and model_validation/ runners that use Hydra-based configuration.

To use vLLM for serving quantized models on Linux, add --extra vllm together with --extra cu130:

uv sync --extra cu130 --extra dev --extra visualize --extra vllm

Note: --extra vllm is only compatible with --extra cu130. Recent vLLM releases require torch>=2.10, whose wheels are only published for the cu130 index. Combining --extra vllm with cpu / mps / cu118 / cu121 / cu124 / cu126 / cu128 is rejected by uv at lock time.

Note: --extra vllm may take a long time on the first run if a pre-built xformers wheel is not available for your Python/CUDA combination (e.g. Python 3.13). Using Python 3.12 typically avoids this.

Running commands (uv environment)

In the environment created by uv sync, you can run commands in two ways:

Option 1: Use uv run (no activation needed)

uv run pytest tests/ -v
uv run python example/example_gptq.py
uv run black --check onecomp/

Option 2: Activate the virtual environment (traditional approach)

source .venv/bin/activate
pytest tests/ -v
python example/example_gptq.py
black --check onecomp/

First, install PyTorch with CUDA support for your environment

pip install torch --index-url https://download.pytorch.org/whl/cu128

Then install onecomp with development dependencies

pip install -e ".[dev]"

Replace `cu128` with the appropriate variant for your environment: `cpu`, `cu118`, `cu121`, `cu124`, `cu126`, `cu128`, or `cu130`.

#### Pre-commit

After installing development dependencies (`--extra dev` with uv, or `pip install -e ".[dev]"` with pip), register the Git hooks once:

```bash
pre-commit install

On every git commit, the following checks run automatically:

Common commands:

---

# Run hooks on all files (useful after first install or config changes)
pre-commit run --all-files

---

# uv users (vLLM requires cu130; see Installation for details)
uv sync --extra cu130 --extra vllm

---

##