> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opentrack/opentrack/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Download and install OpenTrack on Windows, Linux, or macOS

## Windows Installation

OpenTrack provides pre-built binaries for Windows users. This is the recommended installation method for most users.

<Steps>
  <Step title="Download OpenTrack">
    Visit the [OpenTrack releases page](https://github.com/opentrack/opentrack/releases) and download the latest version:

    * **Installer (`.exe`)** - Recommended for most users
    * **Portable archive (`.7z`)** - For USB stick installations

    <Note>
      The portable version supports [truly portable installations on USB sticks](https://github.com/opentrack/opentrack/wiki/portable-mode-for-USB-sticks).
    </Note>
  </Step>

  <Step title="Run the installer">
    Double-click the downloaded `.exe` file and follow the installation wizard.

    The installer will:

    * Install OpenTrack to `C:\Program Files\opentrack` (or your chosen location)
    * Create Start Menu shortcuts
    * Register file associations
  </Step>

  <Step title="Launch OpenTrack">
    Open OpenTrack from the Start Menu or desktop shortcut.

    On first launch, Windows may prompt for firewall permissions if you're using network-based tracking (UDP) or protocols.
  </Step>
</Steps>

### Portable Installation (Windows)

For a portable installation that can run from a USB stick:

<Steps>
  <Step title="Download the portable archive">
    Download the `.7z` archive from the [releases page](https://github.com/opentrack/opentrack/releases).
  </Step>

  <Step title="Extract to USB stick">
    Extract the archive to your USB stick or desired location using 7-Zip or WinRAR.
  </Step>

  <Step title="Run opentrack.exe">
    Navigate to the extracted folder and run `opentrack.exe` directly. All settings will be stored in the same folder.
  </Step>
</Steps>

***

## Linux Installation

OpenTrack can be built from source on Linux systems. Pre-built packages may be available for some distributions.

### Building from Source

<Steps>
  <Step title="Install dependencies">
    Install required build tools and libraries:

    ```bash Ubuntu/Debian theme={null}
    sudo apt-get update
    sudo apt-get install build-essential cmake git
    sudo apt-get install qtbase5-dev qttools5-dev qtmultimedia5-dev
    sudo apt-get install libopencv-dev libprocps-dev
    ```

    ```bash Fedora theme={null}
    sudo dnf groupinstall "Development Tools"
    sudo dnf install cmake git
    sudo dnf install qt5-qtbase-devel qt5-qttools-devel qt5-qtmultimedia-devel
    sudo dnf install opencv-devel procps-ng-devel
    ```

    ```bash Arch Linux theme={null}
    sudo pacman -S base-devel cmake git
    sudo pacman -S qt5-base qt5-tools qt5-multimedia
    sudo pacman -S opencv procps-ng
    ```
  </Step>

  <Step title="Clone the repository">
    Clone the OpenTrack source code:

    ```bash theme={null}
    git clone https://github.com/opentrack/opentrack.git
    cd opentrack
    ```
  </Step>

  <Step title="Build OpenTrack">
    Create a build directory and compile:

    ```bash theme={null}
    mkdir build && cd build
    cmake ..
    make -j$(nproc)
    ```

    <Note>
      The `-j$(nproc)` flag uses all available CPU cores for faster compilation.
    </Note>
  </Step>

  <Step title="Install OpenTrack">
    Install to the default location:

    ```bash theme={null}
    sudo make install
    ```

    Or run directly from the build directory:

    ```bash theme={null}
    ./install/bin/opentrack
    ```
  </Step>
</Steps>

### Advanced Build Options

For detailed build instructions and troubleshooting, see:

* [Linux build instructions](https://github.com/opentrack/opentrack/wiki/Building-on-Linux)
* [Hacking on OpenTrack](https://github.com/opentrack/opentrack/wiki/Hacking-opentrack)

***

## macOS Installation

<Warning>
  macOS support is currently **unmaintained**. The software may work but is not actively tested or updated.
</Warning>

### Building from Source (macOS)

<Steps>
  <Step title="Install Xcode and Homebrew">
    Install Xcode Command Line Tools:

    ```bash theme={null}
    xcode-select --install
    ```

    Install Homebrew if not already installed:

    ```bash theme={null}
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    ```
  </Step>

  <Step title="Install dependencies">
    Use Homebrew to install required packages:

    ```bash theme={null}
    brew install cmake qt@5 opencv
    ```
  </Step>

  <Step title="Clone and build">
    Clone the repository and build:

    ```bash theme={null}
    git clone https://github.com/opentrack/opentrack.git
    cd opentrack
    mkdir build && cd build
    cmake -DCMAKE_PREFIX_PATH=$(brew --prefix qt@5) ..
    make -j$(sysctl -n hw.ncpu)
    ```
  </Step>

  <Step title="Run OpenTrack">
    Launch the application:

    ```bash theme={null}
    open ./install/opentrack.app
    ```
  </Step>
</Steps>

***

## Compiler Requirements

### Windows

OpenTrack requires one of the following compilers:

* **MinGW-w64** (GCC-based)
* **Microsoft Visual Studio 2015 Update 3** or newer
* **Clang** (via MSVC or MinGW)

For Visual Studio build instructions, see [Building under MS Visual C++ 2017 and later](https://github.com/opentrack/opentrack/wiki/Building-under-MS-Visual-C---2017-and-later).

### Linux

* **GCC** (GNU Compiler Collection)
* **Clang/LLVM**

CMake version 3.13 or later is required on all platforms.

***

## Verifying Installation

After installation, verify OpenTrack is working:

<Steps>
  <Step title="Launch OpenTrack">
    Start the application from your Start Menu (Windows), application launcher (Linux), or Launchpad (macOS).
  </Step>

  <Step title="Check the main window">
    You should see the OpenTrack main window with dropdown menus for:

    * Tracker input
    * Filter
    * Protocol output
  </Step>

  <Step title="View the pose widget">
    The 3D head visualization widget should be visible, showing a wireframe head model.
  </Step>
</Steps>

<Note>
  If you encounter issues, check the [Common Issues](https://github.com/opentrack/opentrack/wiki/common-issues) page on the wiki.
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Set up your first tracker and start tracking
  </Card>

  <Card title="Tracker Documentation" icon="video" href="https://github.com/opentrack/opentrack/wiki">
    Learn about specific trackers and configurations
  </Card>
</CardGroup>