Skip to content

Installation

Choose the install path that matches how you want to run VDL.

Standalone Binary Install

The standalone installers are the default end-user path on macOS, Linux, and Windows.

They install: - the vdl CLI - the vdl-mcp MCP server - no Python runtime dependency on the target machine

They do not delete user data. Downloads, config, state, logs, and cache stay in place across installs and updates.

Install Commands

macOS / Linux:

curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh

Windows:

irm https://bildcraft.gitlab.io/products/video-downloader/vdl/install.ps1 | iex

Default Installer Behavior

Running the installer is safe to repeat.

By default, the installer will:

  1. detect the currently managed install in the install directory
  2. read the target version from release.json
  3. check required dependencies before replacing binaries
  4. install if VDL is missing
  5. update if the installed version is older
  6. do nothing if the same version is already installed
  7. warn and stop if the installed version is newer than the target version
  8. stop safely if the current install is broken, unless you explicitly force a reinstall

If a dependency is missing, the installer fails before replacing the current binaries.

If replacement or final smoke checks fail, the installer restores the previous binaries.

Required Dependencies

Standalone binary installs require: - ffmpeg - ffprobe

These requirements are published in the release manifest and checked before install or update.

Default behavior: - validate dependencies - fail with clear install instructions if anything required is missing

Explicit dependency install: - macOS / Linux: --install-deps - Windows: -InstallDeps

Non-interactive dependency install: - macOS / Linux: --install-deps --yes - Windows: -InstallDeps -Yes

Current first-party dependency automation: - macOS: brew install ffmpeg - common Linux package managers: install ffmpeg - Windows: winget install -e --id Gyan.FFmpeg

If dependency installation succeeds but the current shell still cannot find ffmpeg or ffprobe, the installer stops and tells you to reopen the shell and rerun it.

Installer Flags

macOS / Linux:

curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh -s -- --install-deps
curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh -s -- --install-deps --yes
curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh -s -- --force
curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh -s -- --version 2.0.0

Windows:

powershell -ExecutionPolicy Bypass -File .\install-vdl.ps1 -InstallDeps
powershell -ExecutionPolicy Bypass -File .\install-vdl.ps1 -InstallDeps -Yes
powershell -ExecutionPolicy Bypass -File .\install-vdl.ps1 -Force
powershell -ExecutionPolicy Bypass -File .\install-vdl.ps1 -Version 2.0.0

Meaning: - --install-deps / -InstallDeps: attempt system dependency installation before installing VDL - --yes / -Yes: non-interactive mode for automation - --force / -Force: reinstall even if the version is the same, or recover a broken managed install - --version / -Version: install a specific released version

Local Archive Install

Windows also supports local archive installs for smoke testing and release validation:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -ArchivePath .\out\vdl-<version>-x86_64-pc-windows-msvc.zip

If a sibling checksum file exists at:

.\out\vdl-<version>-x86_64-pc-windows-msvc.zip.sha256

the installer verifies it before continuing.

Install Locations

macOS / Linux binaries: - ~/.local/bin/vdl - ~/.local/bin/vdl-mcp

Windows binaries: - %USERPROFILE%\.local\bin\vdl.exe - %USERPROFILE%\.local\bin\vdl-mcp.exe

If the install directory is not on PATH, install still succeeds but the installer prints a warning.

Verify

vdl --version
vdl doctor

Expected result: - the installed version matches the target version - vdl doctor reports required tools as available

Upgrade

Re-run the installer command for your platform.

Default meaning: - install latest if missing - update to latest if older - no-op if already latest

Uninstall

macOS / Linux:

rm -f ~/.local/bin/vdl ~/.local/bin/vdl-mcp

Windows:

Remove-Item "$env:USERPROFILE\.local\bin\vdl.exe" -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.local\bin\vdl-mcp.exe" -ErrorAction SilentlyContinue

Optional user-data cleanup is separate from uninstall.

uv Tool Install

Use this only when you intentionally want a Python-managed non-binary install.

uv tool install vdl

Upgrade:

uv tool upgrade vdl

Developer Checkout

For local development:

git clone https://gitlab.com/bildcraft/products/video-downloader
cd video-downloader
uv sync --all-extras --dev
PYTHONPATH=src uv run vdl --version

Next Steps