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:

curl https://download.pactflow.io/drift/<version>/macos-aarch64.tgz | tar xz

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.

Install Optional Components

The Drift download includes everything you need to test OpenAPI and AsyncAPI documents. Some plugins, such as Kafka, Amazon SNS and SQS, gRPC, and MCP, are optional components that you install separately:

drift component install kafka

To see all available components, run drift component list --all. For more information, see Managing Components.

Update Drift

To update an existing installation, including any optional components:

drift component update

Setting Up Your PATH

  1. 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

  2. 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:
© 2026
Publication date: