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.

1. Download the latest release

   Visit the releases page and download the archive for your platform.

   The prepackaged binary includes:

   • Executable binary
   • Pre-built JMdict dictionary
   • All required dependencies
2. Extract the archive

   Unpack the downloaded archive to a location of your choice.

   Choose a permanent location - meikipop will create a config.ini file in the same directory.

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

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.

All platforms: Run from source

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

macOS users must run from source - prepackaged binaries are not available for macOS.

Prerequisites

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

macOS

# Check your Python version
python3 --version

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

macOS: Set required permissions

macOS requires specific permissions for meikipop to capture screen content and respond to hotkeys.

1. Open System Preferences

   Navigate to System Preferences > Security & Privacy > Privacy

2. Grant permissions to your terminal

   Add and enable your terminal application (Terminal.app, iTerm2, etc.) in:

   • Input Monitoring
   • Screen Recording
   • Accessibility
3. Restart your terminal

   Close and reopen your terminal for the permissions to take effect.

Download and install

1. Get the source code

   Choose one of these methods:

   Git clone

   git clone https://github.com/rtr46/meikipop.git
   cd meikipop
   
2. Install Python dependencies

   Install the required packages:

   pip install -r requirements.txt
   

   Consider using a virtual environment to isolate meikipop’s dependencies:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   
3. Build the dictionary

   Install the dictionary build tool and create the optimized dictionary:

   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

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

4. Run meikipop

   Start the application:

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

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)

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.

Troubleshooting

Dictionary failed to load

Make sure you’ve run the dictionary build script:

pip install lxml
python -m scripts.build_dictionary

Or copy jmdict_enhanced.pkl from a prepackaged binary distribution.

Import errors or missing modules

Reinstall dependencies:

pip install -r requirements.txt --force-reinstall

macOS: Popup doesn't appear

Verify that you’ve granted all required permissions:

• Input Monitoring
• Screen Recording
• Accessibility

Restart your terminal after granting permissions.

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

Next steps

Quickstart guide

Learn how to use meikipop for your first lookup

Configuration

Customize hotkeys, themes, and scan modes