Deploy Garak 0.17.0 LLM Security Scanner [Install]

Why does pip install garak print success, then garak --version say the command isn’t found – or worse, install nothing at all?

That burned an afternoon on a “fresh” laptop. The fix path below is for Garak 0.17.0 only (PyPI release dated 9 Sep 2026): NVIDIA’s Generative AI Red-teaming & Assessment Kit. It hits models and apps with jailbreak, injection, leakage, and toxicity probes. Framing for the method sits in the garak paper (arXiv:2406.11036); day-one work is getting the binary on a sane Python, not touring every probe class.

Requirements → install → minimum config → verify → the failures people actually hit → upgrade/uninstall. Commands first.

System requirements before you touch pip

As of 0.17.0, Python is a hard gate. Upstream’s conda line is python>=3.11,<=3.13. Release tasking in 0.17 dropped 3.10 and added 3.13; main-branch requires-python is >=3.11. Stay inside 3.11-3.13 or stop here.

Local Hugging Face targets need their own weights on top of that ~9 GB tool stack. Small eval checkpoints are fine. Giant instruct weights are not “one more pip flag.”

Official download source (no random mirrors)

• PyPI: pypi.org/project/garak – 0.17.0 as of 9 Sep 2026
• Source / README: github.com/NVIDIA/garak
• Disk, paths, ops notes: FAQ.md · user guide docs.garak.ai · CLI reference.garak.ai · hub garak.ai

For a laptop red-team install, use pip or an editable clone. Skip random mirrors and “all-in-one” third-party images you can’t pin.

Install Garak 0.17.0 step by step

I keep it in its own venv. Shared torch environments are how import errors show up three weeks later with no obvious cause.

Option A – venv + PyPI (recommended)

# 1) Confirm Python
python3 --version # need 3.11, 3.12, or 3.13

# 2) Fresh venv
python3 -m venv ~/venvs/garak
source ~/venvs/garak/bin/activate # Windows: ~venvsgarakScriptsactivate

# 3) Upgrade installer tooling
python -m pip install -U pip setuptools wheel

# 4) Install latest garak
python -m pip install -U garak

# 5) Pin check
python -m pip show garak | grep -E 'Name|Version'

You want Version: 0.17.0 (or newer if a later cut already landed when you read this).

Option B – conda env (matches upstream docs)

conda create --name garak "python>=3.11,<=3.13" -y
conda activate garak
python -m pip install -U garak

Option C – git main / editable

python -m pip install -U git+https://github.com/NVIDIA/garak.git@main

gh repo clone NVIDIA/garak
cd garak
python -m pip install -e .

Pro tip: Run python -m garak --version the second pip finishes. Don’t export API keys first. A large share of “garak is broken” reports are the wrong interpreter.

First-time configuration (minimum viable)

No config file required for a smoke test. On first run, garak creates XDG locations: data/reports/log under $XDG_DATA_HOME/garak (Linux default ~/.local/share/garak/), config under $XDG_CONFIG_HOME/garak (default ~/.config/garak/). That split is intentional – and it’s what breaks naive CI artifact globs later.

export OPENAI_API_KEY="sk-..." # OpenAI-compatible
export NIM_API_KEY="..." # NVIDIA NIM
export HF_INFERENCE_TOKEN="hf_..." # optional HF Inference API
export GROQ_API_KEY="..."

CLI naming moved to “target.” Equivalent pairs today per the CLI reference:

--target_type / -t # use this
--model_type / -m # alias
--target_name / -n
--model_name # alias

Probe selection: unified --spec. --probes still maps through but is deprecated.

mkdir -p ~/.config/garak
cat > ~/.config/garak/garak.site.yaml <<'EOF'
reporting:
 report_dir: garak_runs
system:
 parallel_attempts: 8
EOF

CI tip in one line: absolute reporting.report_dir, or XDG_DATA_HOME=$PWD/.garak-data, so uploads never chase /root/.local/share.

Verify the install works

python -m garak --version
python -m garak --list_generators | head
python -m garak --list_detectors | head

Banner should show v0.17.0 and the NVIDIA/garak URL.

Offline smoke (no key, no GPU) – this is the gate that matters:

python -m garak 
 --target_type test.Repeat 
 --spec probes.lmrc.SlurUsage 
 --generations 1

test.Repeat echoes the prompt. You’re proving plugins load, the use runs, and a report path prints – not scoring a production model.

After keys exist, keep the first live pass tiny and boring:

# REST-style / OpenAI-compatible endpoint you already pay for
export OPENAI_API_KEY="sk-..."
python -m garak --target_type openai --target_name gpt-4o-mini 
 --spec probes.lmrc.Profanity --generations 1 --parallel_attempts 4

# Only if you accept a local weight download + RAM hit
python -m garak --target_type huggingface --target_name sshleifer/tiny-gpt2 
 --spec probes.lmrc.SlurUsage --generations 1

Terminal should print log + garak.<uuid>.report.jsonl. That’s the install receipt.

Ever notice how “successful” ML installs still feel unfinished until one end-to-end path returns a file you can ls? Same here – version strings lie less often than empty site-packages, but the jsonl path is the real handshake.

Common install errors and fixes

The catch is almost never “garak theory.” It’s wheels, PATH, disk, or where files landed.

1. Silent empty install on Python 3.14
GitHub issue #1759: pip install garak can exit 0 while nothing installs – torch/transformers lacked usable cp314 wheels, so resolution no-op’d (Windows reports were loudest). Fix: CPython 3.12 or 3.13, new venv, reinstall. Don’t wait on 3.14 wheels for this stack.

2. “Command not found” after pip success
Wrong interpreter. Use python -m garak inside the activated venv, or put that venv’s bin on PATH.

3. Process dies loading local shards
FAQ territory: external OOM killer. Smaller --target_name, API generator, or free memory. Not a mysterious garak crash loop.

4. Default probe set never finishes
Expected. FAQ practice: --config fast, narrow --spec, and on remote targets try --parallel_attempts 20–40. “Run everything” is research-grade.

5. CI can’t find reports
Default tree is under XDG data home (~/.local/share/garak/...). Set reporting.report_dir into the workspace or export XDG_DATA_HOME before the job (see config section).

6. Old flags in scripts
--probes dan,promptinject → --spec probes.dan,probes.promptinject. Prefer --target_type / --target_name.

Release notes for 0.17.0 also tag probe results with EU AI Act mapping. Compliance digests get a grouping hook “for free”; you don’t flip a special install flag to turn it on.

Upgrade and uninstall

Upgrade

source ~/venvs/garak/bin/activate
python -m pip install -U garak
python -m garak --version

python -m pip install -U git+https://github.com/NVIDIA/garak.git@main

After a major bump, re-read release notes before reusing old YAML. Prefer fresh --spec on the CLI until configs catch up.

Uninstall / cleanup

python -m pip uninstall garak -y
# optional: wipe user data (reports, logs, caches)
rm -rf ~/.local/share/garak ~/.cache/garak ~/.config/garak
rm -rf ~/venvs/garak
conda deactivate && conda env remove -n garak

Wheel uninstall leaves XDG trees on purpose – that’s run history, not leftover package files.

FAQ

Do I need a GPU to run garak?

No. GPU only matters when the target loads locally. API endpoints are CPU + network.

Where did my report.jsonl go after a successful scan?

Linux default: under XDG data home, commonly ~/.local/share/garak/garak_runs/, with garak.log nearby. The CLI prints the path. In GitHub Actions, pin reporting.report_dir or XDG_DATA_HOME so the uploader isn’t searching /root/.local/share.

Is Docker the supported install for 0.17.0?

Not the primary path – upstream pushes pip and conda. If you roll your own image anyway: Python 3.12-slim base, venv inside the image, garak from PyPI, mount a report volume, pass API keys at runtime. Don’t bake secrets into layers. Heavy “eval factory” containers are a different workflow than a red-team laptop.

Next: create the venv, pip install -U garak, python -m garak --version, then the test.Repeat one-liner. When a report path appears, aim --target_type at your real endpoint with a narrow --spec.