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

# Installation

> Install meikipop using prepackaged binaries for Windows and Linux, or run from source on any platform including macOS.

Choose the installation method that works best for your platform and use case.

## Windows and Linux (X11): Prepackaged binaries

This is the easiest way to run meikipop on Windows and Linux. No Python installation required.

<Steps>
  <Step title="Download the latest release">
    Visit the [releases page](https://github.com/rtr46/meikipop/releases/latest) and download the archive for your platform.

    The prepackaged binary includes:

    * Executable binary
    * Pre-built JMdict dictionary
    * All required dependencies
  </Step>

  <Step title="Extract the archive">
    Unpack the downloaded archive to a location of your choice.

    <Tip>
      Choose a permanent location - meikipop will create a `config.ini` file in the same directory.
    </Tip>
  </Step>

  <Step title="Run meikipop">
    Launch the executable from the extracted folder. An icon will appear in your system tray.

    On first launch, you'll be prompted to select a scan region if you're in region mode.
  </Step>
</Steps>

<Info>
  **Recommended for most users:** Prepackaged binaries are the fastest way to get started if you don't need to modify meikipop's behavior or use custom OCR providers.
</Info>

## All platforms: Run from source

Running from source gives you full control over meikipop's behavior and allows you to use custom OCR providers.

<Note>
  macOS users must run from source - prepackaged binaries are not available for macOS.
</Note>

### Prerequisites

You'll need Python 3.10 or later installed on your system.

<CodeGroup>
  ```bash macOS theme={null}
  # Check your Python version
  python3 --version

  # Install Python 3.10+ if needed using Homebrew
  brew install python@3.10
  ```

  ```bash Linux theme={null}
  # Check your Python version
  python3 --version

  # Install Python 3.10+ if needed (Ubuntu/Debian)
  sudo apt update
  sudo apt install python3.10 python3-pip
  ```

  ```bash Windows theme={null}
  # Check your Python version
  python --version

  # Download from python.org if needed
  # https://www.python.org/downloads/
  ```
</CodeGroup>

### macOS: Set required permissions

<Warning>
  macOS requires specific permissions for meikipop to capture screen content and respond to hotkeys.
</Warning>

<Steps>
  <Step title="Open System Preferences">
    Navigate to **System Preferences** > **Security & Privacy** > **Privacy**
  </Step>

  <Step title="Grant permissions to your terminal">
    Add and enable your terminal application (Terminal.app, iTerm2, etc.) in:

    * **Input Monitoring**
    * **Screen Recording**
    * **Accessibility**
  </Step>

  <Step title="Restart your terminal">
    Close and reopen your terminal for the permissions to take effect.
  </Step>
</Steps>

### Download and install

<Steps>
  <Step title="Get the source code">
    Choose one of these methods:

    <CodeGroup>
      ```bash Git clone theme={null}
      git clone https://github.com/rtr46/meikipop.git
      cd meikipop
      ```

      ```bash Download archive theme={null}
      # Download the archive
      curl -L https://github.com/rtr46/meikipop/archive/refs/heads/main.zip -o meikipop.zip

      # Extract and navigate
      unzip meikipop.zip
      cd meikipop-main
      ```
    </CodeGroup>
  </Step>

  <Step title="Install Python dependencies">
    Install the required packages:

    ```bash theme={null}
    pip install -r requirements.txt
    ```

    <Tip>
      Consider using a virtual environment to isolate meikipop's dependencies:

      ```bash theme={null}
      python -m venv venv
      source venv/bin/activate  # On Windows: venv\Scripts\activate
      pip install -r requirements.txt
      ```
    </Tip>
  </Step>

  <Step title="Build the dictionary">
    Install the dictionary build tool and create the optimized dictionary:

    ```bash theme={null}
    pip install lxml
    python -m scripts.build_dictionary
    ```

    This process will:

    1. Download JMdict from the official source
    2. Process the dictionary into an optimized format
    3. Download and process kanjidic2
    4. Create `jmdict_enhanced.pkl`

    <Info>
      The dictionary build takes a few minutes. Alternatively, you can copy a pre-built dictionary from one of the binary distributions.
    </Info>
  </Step>

  <Step title="Run meikipop">
    Start the application:

    ```bash theme={null}
    python -m src.main
    ```

    You'll see a confirmation message:

    ```
    --------------------------------------------------
    meikipop.v.1.11.0 is running in the background.

      - To use: Press and hold 'shift' over Japanese text.
      - To configure or change scan area: Right-click the icon in your system tray.
      - Make sure to checkout the auto scan mode!
      - To exit: Press Ctrl+C in this terminal.

    --------------------------------------------------
    ```
  </Step>
</Steps>

## Verify installation

After installation, verify that meikipop is running:

1. **Check the system tray** - You should see a meikipop icon
2. **Right-click the icon** - A menu should appear with settings options
3. **Test a lookup** - Move your mouse over Japanese text and press the hotkey (Shift by default)

<Warning>
  **macOS beta limitations:** The tray icon may not appear consistently. If you don't see it, meikipop is still running - you can configure it through the `config.ini` file in the application directory.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dictionary failed to load">
    Make sure you've run the dictionary build script:

    ```bash theme={null}
    pip install lxml
    python -m scripts.build_dictionary
    ```

    Or copy `jmdict_enhanced.pkl` from a prepackaged binary distribution.
  </Accordion>

  <Accordion title="Import errors or missing modules">
    Reinstall dependencies:

    ```bash theme={null}
    pip install -r requirements.txt --force-reinstall
    ```
  </Accordion>

  <Accordion title="macOS: Popup doesn't appear">
    Verify that you've granted all required permissions:

    * Input Monitoring
    * Screen Recording
    * Accessibility

    Restart your terminal after granting permissions.
  </Accordion>

  <Accordion title="Linux: No system tray icon">
    Some Linux desktop environments don't show system tray icons by default. Try installing a tray extension:

    * **GNOME:** Install "AppIndicator and KStatusNotifierItem Support" extension
    * **KDE Plasma:** System tray should work by default
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart guide" icon="rocket" href="/quickstart">
    Learn how to use meikipop for your first lookup
  </Card>

  <Card title="Configuration" icon="gear" href="/user-guide/configuration">
    Customize hotkeys, themes, and scan modes
  </Card>
</CardGroup>