Installing VDL

Overview¶

Choose the installation method that best fits your operating system and workflow.

After installation, verify that the CLI is available:

vdl --version

Linux and macOS¶

Shell Installer¶

The shell installer is the quickest way to install VDL on Linux and macOS.

curl -fsSL https://get.varavel.com/vdl | sh

For more installation options using this installer, visit https://get.varavel.com/vdl.

Install a specific version:

curl -fsSL https://get.varavel.com/vdl | VERSION=vx.x.x sh

Replace vx.x.x with the release tag you want to install, for example v0.1.0.

Homebrew¶

Use Homebrew if you prefer managing CLI tools through taps.

brew install varavelio/tap/vdl

Install the latest prerelease:

brew install varavelio/tap/vdl-next

Install a specific version:

brew install varavelio/tap/[email protected]

Replace x.x.x with the version you want to install.

Windows¶

Use the PowerShell installer on Windows.

irm https://get.varavel.com/vdl.ps1 | iex

For more installation options using this installer, visit https://get.varavel.com/vdl.ps1.

Install a specific version:

$env:VERSION = "vx.x.x"; irm https://get.varavel.com/vdl.ps1 | iex

Replace vx.x.x with the release tag you want to install, for example v0.1.0.

NPM¶

The npm package is cross-platform and works well when VDL should be pinned per project.

Local Project Install¶

This is the recommended npm workflow for teams because it keeps every developer and CI job on the same VDL version.

npm install --save-dev @varavel/vdl

Then call VDL from package scripts, for example:

{
  "scripts": {
    "vdl:generate": "vdl generate",
    "vdl:format": "vdl format"
  }
}

Global Install¶

Use a global install when you want vdl available system-wide.

npm install --global @varavel/vdl

Install the latest prerelease:

npm install --global @varavel/vdl@next

Install a specific version:

npm install --global @varavel/[email protected]

For package details, visit the npm package page.

Docker¶

The official VDL image is available on both Docker Hub and the GitHub Container Registry. It provides a minimal, multi-arch container with the vdl binary at /usr/local/bin/vdl.

The image supports linux/amd64 and linux/arm64.

Run directly¶

Call vdl commands without installing anything on your host, to work with files in your current directory, mount it as a volume:

docker run --rm -v "$(pwd):/workspace" -w /workspace varavel/vdl:latest generate
docker run --rm -v "$(pwd):/workspace" -w /workspace varavel/vdl:latest format

Shell alias¶

If you prefer the native vdl experience without installing anything, add an alias to your shell profile (~/.bashrc, ~/.zshrc, etc.):

alias vdl='docker run --rm -v "$(pwd):/workspace" -w /workspace varavel/vdl:latest'

Once the alias is in place you can use vdl as if it were installed locally:

vdl init
vdl generate
vdl format

Pin a version¶

Replace latest with a specific version tag to ensure reproducible builds across your team and CI:

docker run --rm varavel/vdl:0.1.0 version

alias vdl='docker run --rm -v "$(pwd):/workspace" -w /workspace varavel/vdl:0.1.0'

Copy the binary into your own images¶

VDL is useful inside CI pipelines and builder images that need to invoke code generation. Copy the binary directly from the official image without compiling or installing anything:

FROM your-base-image
COPY --from=varavel/vdl:latest /usr/local/bin/vdl /usr/local/bin/vdl

This places vdl on the default PATH of your image so it is immediately usable in downstream steps.

Use the GitHub Container Registry¶

The same image is also published to GHCR. Prefer this registry when you need tighter integration with GitHub Actions or when Docker Hub pull rate limits are a concern:

docker run --rm ghcr.io/varavelio/vdl:latest format

FROM your-base-image
COPY --from=ghcr.io/varavelio/vdl:latest /usr/local/bin/vdl /usr/local/bin/vdl

Manual Downloads¶

You can download prebuilt binaries from the VDL releases page.

Manual installation is useful when you need to:

• install VDL in an environment without package managers
• mirror binaries internally
• pin a binary in a custom CI image
• inspect release assets before installing

Download the archive for your operating system and architecture, extract it, and place the vdl binary somewhere on your PATH.

Choosing A Method¶

• Use the shell installer for the fastest Linux/macOS setup.
• Use Homebrew if you already manage developer tools with Homebrew.
• Use the PowerShell installer on Windows.
• Use local npm install for project-pinned VDL versions in Node-based repositories.
• Use Docker when you want to run VDL without installing anything locally, or when you need to embed the VDL binary inside your own container images.
• Use manual downloads for custom distribution, offline environments, or CI images.