Development setup

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:

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

Set up virtual environment (recommended)

Using a virtual environment keeps your dependencies isolated:

python -m venv venv
venv\Scripts\activate

python -m venv venv
.\venv\Scripts\Activate.ps1

python3 -m venv venv
source venv/bin/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:

Verify your setup

Ensure everything is configured correctly:

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

ImportError: No module named 'src'

You’re running the script incorrectly. Always use:

python -m src.main

Not:

python src/main.py  # Wrong!

ModuleNotFoundError: No module named 'PyQt6'

Dependencies aren’t installed. Run:

pip install -r requirements.txt

RuntimeError: Failed to load dictionary

The jmdict_enhanced.pkl file is missing from the data/ directory. See Build the dictionary section.

Linux: Could not connect to X server

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.

macOS: Keyboard hotkey not working

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.

Windows: The 'keyboard' library failed to import

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:

Learn about the architecture to understand how meikipop works
Build executables with PyInstaller
Start contributing by fixing bugs or adding features

Join the discussion on GitHub Issues if you need help or want to propose changes to meikipop.

Custom OCR Providers

Contributing

Development setup

Prerequisites

Clone the repository

Set up virtual environment (recommended)

Install dependencies

Understanding the dependencies

Build the dictionary

Option 1: Download prebuilt dictionary (faster)

Option 2: Build from source (requires lxml)

Verify your setup

Development workflow

Running from source

Configuration file

Logging

Code style

Troubleshooting

Next steps

​Prerequisites

​Clone the repository

​Set up virtual environment (recommended)

​Install dependencies

​Understanding the dependencies

​Build the dictionary

​Option 1: Download prebuilt dictionary (faster)

​Option 2: Build from source (requires lxml)

​Verify your setup

​Development workflow

​Running from source

​Configuration file

​Logging

​Code style

​Troubleshooting

​Next steps

Prerequisites

Clone the repository

Set up virtual environment (recommended)

Install dependencies

Understanding the dependencies

Build the dictionary

Option 1: Download prebuilt dictionary (faster)

Option 2: Build from source (requires lxml)

Verify your setup

Development workflow

Running from source

Configuration file

Logging

Code style

Troubleshooting

Next steps