Skip to main content
This guide walks you through setting up a development environment for meikipop on Windows, Linux, and macOS.

​
Prerequisites

Before you begin, make sure you have the following installed:
1
Python 3.10 or higher
2
Meikipop requires Python 3.10+. Verify your installation:
3
python --version
# or on some systems
python3 --version
5
For cloning the repository and version control:
6
git --version
7
Platform-specific requirements
8
Windows
No additional system requirements. Python packages will handle everything.
Linux (X11)
Make sure you’re running X11 (not Wayland). Meikipop uses X11-specific APIs for keyboard monitoring.
# Verify you're using X11
echo $XDG_SESSION_TYPE
# Should output: x11
You’ll also need development headers:
# Debian/Ubuntu
sudo apt-get install python3-dev libx11-dev

# Fedora
sudo dnf install python3-devel libX11-devel

# Arch
sudo pacman -S python libx11
macOS
Meikipop support on macOS is currently in beta. The system tray may not work reliably, and you may need to configure settings via config.ini directly.
You’ll need to grant permissions for meikipop to work:
  1. Open System Preferences → Security & Privacy → Privacy
  2. Add your terminal app (Terminal.app, iTerm2, etc.) to:
    • Input Monitoring
    • Screen Recording
    • Accessibility
You may need to restart your terminal after granting permissions.

​
Clone the repository

Get the latest source code from GitHub: 
git clone https://github.com/rtr46/meikipop.git
cd meikipop
Alternatively, download the source archive: 
# Download and extract
wget https://github.com/rtr46/meikipop/archive/refs/heads/main.zip
unzip main.zip
cd meikipop-main
Using a virtual environment keeps your dependencies isolated: 
python -m venv venv
venv\Scripts\activate
You should see (venv) in your terminal prompt when the environment is active.

​
Install dependencies

Install all required Python packages from requirements.txt: 
pip install -r requirements.txt

​
Understanding the dependencies

Here are the key dependencies (from requirements.txt): 
PyQt6>=6.9.1              # GUI framework for popup and tray icon
pynput>=1.7.8              # Cross-platform mouse control
mss>=10.0.0                # Fast screenshot capture
requests>=2.32.4           # HTTP client for OCR APIs
Pillow>=11.2.1             # Image processing
betterproto>=2.0.0b7       # Protocol buffers for Google Lens
protobuf>=6.33.1           # Protocol buffer runtime
websockets>=15.0.1         # WebSocket support for owocr
meikiocr>=0.3.1            # Local OCR provider

# Platform-specific dependencies
keyboard~=0.13.5; sys_platform == 'win32'                # Windows keyboard input
pyobjc-framework-Quartz>=10.0; sys_platform == 'darwin'  # macOS screen APIs
pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'   # macOS UI APIs
python-xlib~=0.33; sys_platform == 'linux'               # Linux X11 APIs
onnxruntime==1.20.1; sys_platform == 'win32'            # Pinned for Windows stability
Platform-specific dependencies are automatically installed only on the relevant operating system.

​
Build the dictionary

Meikipop requires a preprocessed dictionary file for fast lookups. You have two options:

​
Option 1: Download prebuilt dictionary (faster)

Download jmdict_enhanced.pkl from the latest release: 
# Download from releases page
wget https://github.com/rtr46/meikipop/releases/latest/download/data.zip
unzip data.zip
# This extracts jmdict_enhanced.pkl to the data/ directory

​
Option 2: Build from source (requires lxml)

Build the dictionary yourself:
1
Install build dependencies
2
pip install lxml
3
Run the build script
4
python -m scripts.build_dictionary
5
This downloads the latest JMdict XML data and processes it into the optimized .pkl format.
6
Building the dictionary can take several minutes depending on your system.

​
Verify your setup

Ensure everything is configured correctly:
1
Check directory structure
2
Your project should look like this:
3
meikipop/
├── data/
│   └── jmdict_enhanced.pkl    # Dictionary file (required)
├── src/
│   ├── main.py                # Entry point
│   ├── config/
│   ├── dictionary/
│   ├── gui/
│   ├── ocr/
│   ├── screenshot/
│   └── utils/
├── requirements.txt
└── config.ini                  # Created on first run
4
Run meikipop
5
python -m src.main
6
You should see output like:
7
--------------------------------------------------
meikipop.0.x.x 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.

--------------------------------------------------
8
Test basic functionality
9
  • The app should prompt you to select a scan region (first run only)
  • A system tray icon should appear
  • Position some Japanese text on your screen
  • Hold the hotkey (Shift by default) and hover over the text
  • A popup with dictionary entries should appear

    • ​
    Development workflow

    ​
    Running from source

    Always run meikipop as a module: 
    python -m src.main
    Do not run python src/main.py directly. This breaks relative imports within the application.

    ​
    Configuration file

    Settings are stored in config.ini in the project root: 
    [settings]
hotkey = shift
ocr_provider = Google Lens v2
scan_region = region
auto_scan_mode = False
font_family = MS Gothic
color_background = #1e1e1e
# ... and more
    Changes via the GUI are saved automatically. You can also edit this file directly.

    ​
    Logging

    Meikipop outputs debug information to the console. To see more detailed logs, modify src/utils/logger.py.

    ​
    Code style

    The codebase generally follows PEP 8. Key conventions:
    • Snake_case for functions and variables
    • PascalCase for classes
    • Module-level constants in UPPER_CASE
    • Descriptive variable names (e.g., hit_scan_result not hsr)

    ​
    Troubleshooting

    You’re running the script incorrectly. Always use:
    python -m src.main
    Not:
    python src/main.py  # Wrong!
    Dependencies aren’t installed. Run:
    pip install -r requirements.txt
    The jmdict_enhanced.pkl file is missing from the data/ directory. See Build the dictionary section.
    You’re either:
    • Not running X11 (check with echo $XDG_SESSION_TYPE)
    • Missing the DISPLAY environment variable
    • Running without a graphical session
    Meikipop requires a graphical X11 session to function.
    Make sure you’ve granted Input Monitoring permissions to your terminal app in System Preferences → Security & Privacy → Privacy → Input Monitoring.You may need to restart the terminal after granting permissions.
    On Windows, the keyboard library sometimes requires administrator privileges. Try running your terminal as administrator.

    ​
    Next steps

    Now that your environment is set up, you can:
    Join the discussion on GitHub Issues if you need help or want to propose changes to meikipop.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us