# Installation (Workbench)

### Windows (Recommended)

#### Option 1: Download Release (Easiest)

1. Go to [GitHub Releases](https://github.com/Supervertaler/Supervertaler-Workbench/releases)
2. Download the latest `.zip` file
3. Extract to a folder of your choice
4. Run `Supervertaler.exe`
5. *Optional:* double-click **`Add Supervertaler to Start Menu.cmd`** once to add a Start Menu shortcut, so you can launch the app from the Start Menu (or pin it to the taskbar) like any installed program. This is just a friendly wrapper around `create_start_menu_shortcut.ps1` that bypasses Windows' default PowerShell ExecutionPolicy without changing any system-wide settings.

#### Option 2: Run from Source

If you want the latest development version or want to contribute:

```bash
# Clone the repository
git clone https://github.com/Supervertaler/Supervertaler-Workbench.git
cd Supervertaler

# Create virtual environment
python -m venv venv
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python Supervertaler.py
```

### macOS

The macOS install method depends on your Mac's processor.

#### Apple Silicon (M1, M2, M3, M4) — Download Release

1. Go to [GitHub Releases](https://github.com/Supervertaler/Supervertaler-Workbench/releases)
2. Download the latest `.dmg` file
3. Open the `.dmg` and drag **Supervertaler** to your Applications folder
4. Launch from Spotlight or Launchpad

#### Intel Macs — Install via pip

The published macOS `.dmg` is built for Apple Silicon only and will not run on Intel hardware. Intel Mac users need to install via pip and provide a system Java for the Okapi sidecar (which handles Word, Excel, HTML and other office-document imports).

```bash
# 1. Install Homebrew (skip if already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install Python 3 (skip if already installed)
brew install python@3.12

# 3. Install Java 17 (Eclipse Temurin, free, no Oracle account required)
brew install --cask temurin@17

# 4. Install Supervertaler
pip3 install supervertaler

# 5. Run it
supervertaler
```

If you skip the Java step, Supervertaler shows a friendly dialog at startup with the install command. Plain-text translation, TMX, termbases, etc. all work without Java – only office-document import/export needs it.

On first DOCX import, Supervertaler downloads the Okapi sidecar JAR (\~28 MB) into `~/Library/Application Support/Supervertaler/okapi-sidecar/`. After that, everything runs locally and offline.

#### Run from Source (any Mac)

Follow the [Linux source instructions](#linux) below – the commands are identical except for the spellcheck step, where you'd use `brew install hunspell` instead of `apt install hunspell-*`.

### Linux

Supervertaler is compatible with Linux, though Windows is the primary development platform.

```bash
# Clone the repository
git clone https://github.com/Supervertaler/Supervertaler-Workbench.git
cd Supervertaler

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install Hunspell dictionaries (for spellcheck)
sudo apt install hunspell-en-us hunspell-nl  # Add your languages

# Run the application
python Supervertaler.py
```

:::note **Linux Users:** If you experience crashes related to spellcheck or ChromaDB, see [Linux-Specific Issues](/help/troubleshooting/linux.md). :::

### Dependencies

The main dependencies are automatically installed via `requirements.txt`:

| Package             | Purpose                      |
| ------------------- | ---------------------------- |
| PyQt6               | User interface               |
| openai              | OpenAI GPT integration       |
| anthropic           | Anthropic Claude integration |
| google-generativeai | Google Gemini integration    |
| python-docx         | DOCX file handling           |
| pyspellchecker      | Spellcheck                   |

### Next Steps

After installation:

1. [Set up your API keys](/help/get-started-1/api-keys.md) for AI translation
2. Follow the [Quick Start Guide](/help/get-started-1/quick-start.md)
3. Create your [first translation project](/help/get-started-1/first-project.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://supervertaler.gitbook.io/help/get-started-1/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.