Installation¶
XGrammar Python Package can be installed directly from a prebuilt package or built from source.
Method 1: Prebuilt Package¶
XGrammar supports various platforms:
Operating Systems: Linux, macOS, and Windows
Hardware: CPU, NVIDIA GPUs, AMD GPUs, Apple Silicon, TPU, etc.
Python: 3.9 and later
We provide Python wheels for XGrammar via pip.
python -m pip install xgrammar
We also provide conda packages for XGrammar:
conda install -c conda-forge xgrammar
Use the following command to verify installation:
python -c "import xgrammar; print(xgrammar)"
# Prints: <module 'xgrammar' from '/path-to-env/lib/python3.11/site-packages/xgrammar/__init__.py'>
Method 2: Build XGrammar Python Package from Source¶
This option is useful when you want to make modification or obtain a specific version of XGrammar.
git clone --recursive https://github.com/mlc-ai/xgrammar.git && cd xgrammar
pre-commit install
# Copy cmake config. You can update the config if needed.
cp cmake/config.cmake .
python3 -m pip install --no-build-isolation -e .
XGrammar is a library written in C++ and Python. The editable install will automatically rebuild the package when XGrammar is imported in Python.
Optional: Run Python Tests¶
# Install the test dependencies
python3 -m pip install ".[test]"
# If you have a HuggingFace token, you can run all tests including the ones that have gated models.
huggingface-cli login --token YOUR_HF_TOKEN
python3 -m pytest
# If you do not have a HuggingFace token, you can run a subset of tests that do not require gated models.
python3 -m pytest -m "not hf_token_required"
Method 3: Build XGrammar C++ Library Only¶
XGrammar can also be build as a C++ library. This is useful for using XGrammar in C++ or Rust projects.
XGrammar uses CMake and Ninja to build the C++ library.
git clone --recursive https://github.com/mlc-ai/xgrammar.git && cd xgrammar
# Copy cmake config. You can update the config if needed.
cp cmake/config.cmake .
mkdir build && cd build
cmake -G Ninja ..
ninja
Optional: Run C++ Tests¶
# Run all tests
bash scripts/run_ctest.sh
# Run a subset of tests whose name contains "test_name"
bash scripts/run_ctest.sh test_name