Skip to main content

Installation Guide

This guide covers all installation methods for Drift across different platforms, package managers, and environments.

NPM (Node.JS) Installation​

Run Drift immediately (no global install):

npx @pactflow/drift --help

Install into your project:

npm install --save-dev @pactflow/drift
drift --help

If you prefer a global install (available across shells), install from npm:

npm install -g @pactflow/drift
drift --help

Manual Installation​

To download and install a release manually, choose the appropriate distribution for your operating system:

Linux
curl https://download.pactflow.io/drift/latest/linux-x86_64.tgz | tar xz
./drift --help
macOS (Apple Silicon)
curl https://download.pactflow.io/drift/latest/macos-aarch64.tgz | tar xz
./drift --help
macOS (Intel)
curl https://download.pactflow.io/drift/latest/macos-x86_64.tgz | tar xz
./drift --help
Windows (PowerShell)
curl.exe -o drift.tgz https://download.pactflow.io/drift/latest/windows-x86_64.tgz
tar xz -f drift.tgz
.\drift.exe --help

Pinning to a Specific Version​

To install a specific version of Drift, replace latest in the download URL with the desired version number. For example, to install version 1.2.3:

# macOS (x86_64), version 1.2.3
wget -O drift https://download.pactflow.io/drift/1.2.3/darwin-amd64
./drift --help

URL template:

https://download.pactflow.io/drift/${version}/${osArch}
  • ${version}: The version you want to install (e.g., 1.2.3)
  • ${osArch}: Your OS and architecture (e.g., darwin-amd64, linux-amd64, windows-amd64.exe)

Verify Installation​

After installation, verify that Drift is working correctly:

drift --version

This should output the installed version number. If the command is not found, you may need to add Drift to your system PATH.

Setting Up Your PATH​

Linux & macOS​

If you downloaded the binary directly, you may need to add it to your PATH:

# Option 1: Move to a directory already in PATH
mv ./drift /usr/local/bin/

# Option 2: Add the current directory to PATH
export PATH="$PATH:$(pwd)"

# Option 3: Make it permanent (add to ~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$PATH:/path/to/drift"' >> ~/.zshrc
source ~/.zshrc

Windows​

If you downloaded the binary directly:

  1. Extract the drift.exe file to your desired location
  2. Add the directory to your system PATH:
    • Press Win + X and select "System"
    • Click "Advanced system settings"
    • Click "Environment Variables"
    • Under "System variables", select "Path" and click "Edit"
    • Click "New" and add the directory containing drift.exe
    • Click "OK" and restart your terminal

Troubleshooting​

Command Not Found​

Problem: drift: command not found

Solution: Ensure Drift is in your system PATH. Run echo $PATH to see your current PATH, then verify the Drift binary location is included.

Permission Denied​

Problem: Permission denied when running ./drift

Solution (Linux/macOS):

The released artifacts should already have the correct execution permissions. If you still encounter this error, check your file system mount options or try re-downloading the artifact. If the problem persists, contact support or re-download the correct artifact for your platform.

SSL/TLS Certificate Errors​

Problem: Certificate validation errors when downloading

Solution: Ensure your system's CA certificates are up to date:

macOS:

/Applications/Python\ 3.x/Install\ Certificates.command

Linux:

sudo apt-get install ca-certificates

Windows: Download and run the Mozilla CA bundle

Incompatible Architecture​

Problem: exec format error or similar when running the binary

Solution: Ensure you've downloaded the correct version for your architecture:

  • Linux x86_64 (most common): linux-x86_64.tgz
  • macOS (Apple Silicon/M1/M2/M3): macos-aarch64.tgz
  • macOS (Intel): macos-x86_64.tgz
  • Windows: windows-x86_64.tgz

Check your system architecture:

Linux/macOS:

uname -m

Windows:

wmic os get osarchitecture

Next Steps​

Once you've successfully installed Drift, proceed to the Getting Started guide to run your first test suite.