Install Vexcalibur

Install a release when you want to run vexcalibur as a command. The how-to guides assume this install and call vexcalibur directly.

Vexcalibur needs Python 3.10 through 3.14, the range the project tests. Package metadata alone permits any 3.x, so pip will happily build you an untested environment on a newer interpreter. Check before you start:

python3 -V

On Windows, use the launcher instead. A normal Python installation puts py on your PATH and may not provide python3 at all:

py -V

Install with pip

python3 -m venv .venv
source .venv/bin/activate
pip install vexcalibur
vexcalibur --help

In PowerShell, the virtual environment puts its commands under Scripts:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install vexcalibur
vexcalibur --help

The help output lists the query-osv and generate commands. That’s the success signal.

Activating changes only the current shell. A CI job that starts a fresh shell per step should skip the activate step and call .venv/bin/vexcalibur by its full path instead.

Install with uv

uv tool install creates and manages the environment for you, so there is nothing to activate:

uv tool install vexcalibur
vexcalibur --help

This installs two commands, vexcalibur and vexy. If your shell can’t find them afterward, run uv tool update-shell and open a new shell.

Pin a version

The commands above install the latest release. Vexcalibur is pre-1.0, so command flags, Python APIs, and output detail can change between releases. Pin an exact version in anything you automate.

A pin is a version specifier on the install command:

pip install vexcalibur==0.1.0

0.1.0 is the first release, shown here for the form rather than as a recommendation. The release page lists what you can pin to, and the table below says which release first shipped each output format.

To pin whatever is current, install it and record what you got:

pip install --upgrade vexcalibur
pip freeze | grep '^vexcalibur=='

In PowerShell, grep isn’t available, so filter with Select-String:

pip install --upgrade vexcalibur
pip freeze | Select-String '^vexcalibur=='

--upgrade matters here. Without it, pip treats any already-installed Vexcalibur as satisfying the unbounded requirement and leaves it alone, so you would record whatever was there rather than the current release.

Either one prints a single vexcalibur== line carrying the version you just installed. Put it in your requirements file or lockfile.

A version pin selects a release, not a particular file. PyPI does not let a published file be replaced with different content, but a release contains both a wheel and a source distribution, and which one pip takes depends on the environment and the install options. When you need the same bytes every time, record hashes or use a lockfile that stores them.

What a command reaches

Installing reaches your configured package index. After that, what Vexcalibur contacts depends on the options you pass, not on how you installed it:

Options

Network

--offline with --findings-file

Local files only

--osv-url URL

The mirror you name

--allow-public-osv

https://api.osv.dev

--github-repo OWNER/REPO

The GitHub API

Check that your release has the feature you need

Output formats arrived in different releases, so confirm before you write automation against one:

vexcalibur generate --help

The --format choices list what this release can write. Formats and options arrived in these releases:

Feature

First release

CycloneDX 1.6 output

v0.1.0

OpenVEX 0.2.0 output

v0.2.0

CSAF 2.0 output

v0.3.0

--execution-report

v0.6.0

SPDX 3.0.1 output

v0.7.0

If the format you need is missing, install a newer release rather than working around it.

Install from source instead

Install from a checkout in three cases: you need unreleased work, you’re changing Vexcalibur itself, or a guide’s validation step reads the repository’s schemas. This path needs uv at the version recorded in .tool-versions, and uv sync reaches your package index.

git clone https://github.com/vexcalibur-dev/vexcalibur.git
cd vexcalibur
uv sync --frozen
uv run --frozen vexcalibur --help

Commands then run as uv run --frozen vexcalibur from the repository root. Use the guides from the checkout you’re running rather than the hosted documentation, because the hosted site tracks current development.

Next