> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/skills/skillevaluator/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/skills/skillevaluator/_mcp/server.

# Installation

> Install SkillEvaluator with uv, from source, or in Docker, and choose per-tier extras to keep the footprint small.

This page gets SkillEvaluator installed the way you want it — the full bundle, a smaller per-tier install, an editable source checkout, or a container. No API key is needed to install or to run the deterministic Tier 1 checks; keys only come into play later, for LLM-backed features ([Providers & Credentials](/skills/skillevaluator/configuration)).

If you just want the fastest path to a first result, the [Quickstart](/skills/skillevaluator/quickstart) covers it in one command.

This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.

## Requirements

* [uv](https://docs.astral.sh/uv/getting-started/installation/) for the recommended install paths (plain pip works too — see the source tab below).
* Python 3.12 or 3.13. `uv tool install` and `uv sync` provision a supported interpreter automatically when passed `--python 3.13`; only the plain-pip path needs one on PATH.
* Git for source installs and separately installed security scanners.
* Docker, only for the container install and Tier 3 Docker-mode evaluation.
* No API key is needed for deterministic Tier 1 checks. Full default scanner
  coverage requires the `security` extra plus separate Semgrep, SkillSpector,
  and Gitleaks executables. LLM-backed checks and Tiers 2–3 use a configured provider — see
  [Providers & Credentials](/skills/skillevaluator/configuration).

## Install

#### uv tool (recommended)

Install the full bundle as a standalone tool — uv provisions Python 3.13 for you:

```bash title="Install everything"
uv tool install --python 3.13 "skillevaluator[all] @ git+https://github.com/NVIDIA/SkillEvaluator.git"
```

Prefer a smaller footprint? Swap the extras in the same one-liner:

```bash title="Install with selected extras"
uv tool install --python 3.13 "skillevaluator @ git+https://github.com/NVIDIA/SkillEvaluator.git"            # base checks; scanner checks report INCOMPLETE
uv tool install --python 3.13 "skillevaluator[security] @ git+https://github.com/NVIDIA/SkillEvaluator.git"  # + bundled Python security scanners
uv tool install --python 3.13 "skillevaluator[tier2,tier3] @ git+https://github.com/NVIDIA/SkillEvaluator.git"
```

To pick up the latest commit later, rerun the install with `--reinstall`:

```bash title="Upgrade to the latest commit"
uv tool install --python 3.13 --reinstall "skillevaluator[all] @ git+https://github.com/NVIDIA/SkillEvaluator.git"
```

Then confirm the command resolves:

```bash title="Verify"
skillevaluator --version
```

#### From source

For development or an editable environment, clone the repository and let uv create the environment from the committed lockfile:

```bash title="Clone and sync"
git clone https://github.com/NVIDIA/SkillEvaluator.git
cd SkillEvaluator
uv sync --python 3.13 --all-extras
```

Or with plain pip. This path needs Python 3.12 or 3.13 on PATH — if your system `python3` is newer, use `python3.12 -m venv .venv` instead, or prefer the `uv sync` path above, which provisions a supported Python automatically:

```bash title="Editable install with pip"
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[all]"
```

Editable extras work the same way as the one-liner:

```bash title="Editable install with selected extras"
python -m pip install -e .
python -m pip install -e ".[security]"
python -m pip install -e ".[all,dev]"
```

Then confirm the command resolves inside the environment:

```bash title="Verify"
uv run skillevaluator --version   # uv sync path
skillevaluator --version          # inside the activated pip venv
```

#### Docker

The repository ships a [Dockerfile](https://github.com/NVIDIA/SkillEvaluator/blob/main/Dockerfile) that installs every pip-installable feature (`[all]`). Build the image locally and run a deterministic validation against the included sample skill:

```bash title="Build and run"
docker build -t skillevaluator:local .
docker run --rm skillevaluator:local --version
docker run --rm \
  -v "$PWD/tests/fixtures/skills/simple:/workspace/skills/simple:ro" \
  skillevaluator:local validate /workspace/skills/simple --no-llm --no-dedup
```

The image does not bundle the external Semgrep, SkillSpector, or Gitleaks executables, so their required scanner evidence is incomplete and `validate` exits non-zero — the other checks still run and the report is still produced (see [Troubleshooting](#troubleshooting)). Tier 3 still requires credentials for the selected provider and agent at runtime — pass them into the container as environment variables when you get there.

## Choosing extras

The base package completes the schema, PII, license, quality, Unicode, script-lint, and hygiene checks on its own; scanner-backed checks still run but report INCOMPLETE until the `security` extra and the required external scanner executables are installed. Everything else lives behind an extra:

[Harbor](https://github.com/harbor-framework/harbor) is the open-source agent
evaluation framework that the `tier3` extra installs for live task execution
and environment backends.

| Extra      | What it unlocks                                                                    |
| ---------- | ---------------------------------------------------------------------------------- |
| `llm`      | Shared LLM and embedding clients used by LLM-backed checks, Tier 2, and Tier 3     |
| `tier2`    | Intra-skill deduplication and local-catalog inter-skill similarity; includes `llm` |
| `tier3`    | Docker and cloud live-agent evaluation through Harbor; includes `llm`              |
| `security` | Bandit and pip-audit                                                               |
| `all`      | `tier2`, `tier3`, and `security` in one bundle                                     |
| `dev`      | Build, test, coverage, and formatting tools for contributors                       |

`[all]` installs every SkillEvaluator extra. External scanner tools, Docker, and agent CLIs stay separate no matter which extra you pick.

## System tools

Install the required security scanners separately so their dependency stacks do not constrain the SkillEvaluator distribution:

```bash title="External security scanners"
brew install semgrep gitleaks                                  # macOS
uv tool install semgrep                                       # isolated Python tool environment
uv tool install git+https://github.com/NVIDIA/SkillSpector.git
```

On other systems, install Gitleaks with `go install github.com/gitleaks/gitleaks/v8@latest` or a binary from the [Gitleaks releases](https://github.com/gitleaks/gitleaks/releases). Semgrep and SkillSpector must be on `PATH`, or configured with `SKILLEVALUATOR_SEMGREP_PATH` and `SKILLEVALUATOR_SKILLSPECTOR_PATH`. RHEL 8 and compatible enterprise Linux systems can supply compatible executables independently of the SkillEvaluator Python environment.

Docker is required only for Tier 3 Docker-mode evaluation. Agent CLIs and their credentials are user-supplied — see [Agents & Sandboxes](/skills/skillevaluator/agents-and-sandboxes).

## Verify your install

Two commands tell you whether the install landed:

```bash title="Smoke test"
skillevaluator --version
skillevaluator health-check
```

`--version` confirms the CLI is on PATH — that is the whole smoke test for a Tier 1-only install. `health-check` goes one step further: a quick readiness check of the CLI and the selected live-eval backend (defaults: the `codex` agent, `docker` environment), useful once you plan to run Tier 3. On an install without the `tier3` extra or a configured provider it lists the missing pieces and exits non-zero — expected for a Tier 1-only setup, not a broken install. For a deeper diagnosis, `doctor` covers the same ground plus model verification — see the [CLI Reference](/skills/skillevaluator/cli-reference) for both.

## Troubleshooting

#### The shell can't find skillevaluator after installing

uv installs tools to `~/.local/bin`, which may not be on PATH yet. Run `uv tool update-shell` and open a new terminal.

#### Validation reports INCOMPLETE and exits non-zero

Install any missing required scanner named in the report. The `security` extra supplies Bandit and pip-audit; Semgrep, SkillSpector, and Gitleaks are separate executables. Missing required evidence leaves validation `INCOMPLETE` and non-zero.

## Next steps

#### [Quickstart](/skills/skillevaluator/quickstart)

Run your first evaluation in about two minutes — no API key required.

#### [Providers & Credentials](/skills/skillevaluator/configuration)

Wire up an LLM provider for Tier 2, Tier 3, and LLM-backed checks.