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

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

Review the most common issues.

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.

In this section: