Thanks for your interest in contributing to the RapidOCR Python codebase! This guide explains how to set up your environment, develop, and submit changes for the python directory, including running tests and opening pull requests.
- Python >= 3.6 (3.8+ recommended)
- Git
- A GitHub account
Clone the RapidOCR repository to your machine:
git clone https://github.com/RapidAI/RapidOCR.git
cd RapidOCRIf you have network restrictions, use a mirror or proxy; you can also fork the repo to your account first and clone your fork (see “Preparing to submit” below).
cd pythonUse a virtual environment to avoid conflicts with the system Python:
# Using venv
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# Or using conda
conda create -n rapidocr python=3.10
conda activate rapidocrInstall dependencies (editable install is recommended for local development):
pip install -r requirements.txt
pip install pytest # required to run tests
# Optional: install the package in editable mode for debugging
pip install -e .For inference backends such as ONNX Runtime, follow the documentation to install the corresponding packages (e.g. rapidocr_onnxruntime).
Install pre-commit in your development environment and enable Git pre-commit hooks so that code is automatically formatted and checked (e.g. black, autoflake):
# From the python directory with your venv activated
pip install pre-commit
# Go to the repository root to install Git hooks (.pre-commit-config.yaml is in the root)
cd .. # if you are in python/, go back to the repo root
pre-commit installAfter installation, each git commit will run the configured checks; if they fail, the commit will be rejected. Fix the reported issues and commit again. You can also run checks manually before committing:
# From the repository root
pre-commit run --all-filesFrom the python directory:
# Run all tests
pytest tests/ -v
# Run specific test files
pytest tests/test_input.py -v
pytest tests/test_det_cls_rec.py -v
# Run with coverage (requires pytest-cov)
pytest tests/ -v --cov=rapidocrMake sure the current main branch passes tests in your environment before making changes.
- Pick or open an issue on GitHub Issues.
- Reproduce the problem locally using the code under the
pythondirectory and the issue description. - Locate and fix the code in
rapidocr/ortests/until the issue is resolved.
- (Optional but recommended) Discuss the requirement and approach with maintainers or in an existing issue.
- Implement the feature under
rapidocr/, following the existing style (the project uses black and related tools). - Add unit tests for the new feature.
- Place test files under
python/tests/with names liketest_*.py. - Use pytest. You can refer to existing tests such as
test_input.py,test_det_cls_rec.py, andtest_cli.py. - Put test assets (e.g. images) in
tests/test_files/. - New tests should:
- Reliably verify the behavior you changed (bug fix or new feature).
- Avoid depending on external services not documented in the repo (use mocks or skip when needed).
Example:
# tests/test_xxx.py
import pytest
from pathlib import Path
root_dir = Path(__file__).resolve().parent.parent
tests_dir = root_dir / "tests" / "test_files"
@pytest.fixture()
def engine():
from rapidocr import RapidOCR
return RapidOCR()
def test_your_new_feature(engine):
img_path = tests_dir / "ch_en_num.jpg"
result = engine(img_path)
assert result is not None
# more assertions...From the python directory, run the full test suite again to avoid regressions:
pytest tests/ -vIf some tests are skipped (e.g. missing an inference engine), ensure that the tests you added or changed run and pass in your environment.
- Open the RapidOCR repository.
- Click Fork to create a fork under your GitHub account (e.g.
https://github.com/YOUR_USERNAME/RapidOCR).
If you cloned the upstream repo, add your fork as a remote and push your branch:
# Run from the repository root (RapidOCR)
git remote add myfork https://github.com/YOUR_USERNAME/RapidOCR.git
# If origin points to upstream, keep it; use myfork for pushing
# Create a branch (one branch per issue or feature is recommended)
git checkout -b fix/xxx # or feat/xxx
# Stage and commit your changes under python/
git add python/
git status # confirm only intended files are staged
git commit -m "fix(python): short description"
# Push to your fork
git push myfork fix/xxxPlease follow the Conventional Commits specification for commit messages so maintainers can read and generate changelogs easily. Format:
<type>[optional scope]: <short description>
[optional body]
[optional footer]
Common types:
| Type | Description |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation changes |
style |
Code style (no logic change) |
refactor |
Refactoring |
test |
Tests |
chore |
Build / tooling, etc. |
Examples: fix(python): empty result under certain conditions, feat(python): support xxx input format.
- Open your fork in the browser (e.g.
https://github.com/YOUR_USERNAME/RapidOCR). - After pushing, you will usually see Compare & pull request; click it. Otherwise, select your branch under Branches and click New pull request.
- Set base to
RapidAI/RapidOCRand branchmain(or the default branch). Set head to your fork and your branch (e.g.fix/xxx). - Fill in the PR title and description:
- Title: Short summary (e.g. “Fix: xxx in Python”).
- Description should include:
- Related issue:
Fixes #123orRelated to #123if applicable. - Reason for the change and what was done.
- How to verify (e.g. “
pytest tests/ -vin the python directory passes”).
- Related issue:
- Submit the PR. After review, update your branch locally and push; the PR will update automatically.
| Step | Description |
|---|---|
| 1 | Clone the RapidOCR repository |
| 2 | Go to the python directory, set up a venv, and install dependencies and pytest |
| 3 | Install pre-commit (pip install pre-commit) and run pre-commit install from the repo root |
| 4 | Run unit tests and confirm they pass |
| 5 | Reproduce the issue or implement the new feature |
| 6 | Add or update the corresponding unit tests |
| 7 | Run the full test suite from the python directory and confirm it passes |
| 8 | Fork the main repository to your account |
| 9 | Write commits using Conventional Commits and push to your fork |
| 10 | Open a PR from your fork’s branch to the main repository’s main |
- Code style: The project uses black, autoflake, etc. Pre-commit runs these on commit. You can also run
pre-commit run --all-filesfrom the repo root. - Documentation: See the RapidOCR docs for installation and usage.
- Issues and discussion: Report bugs and suggest features via GitHub Issues.
Thank you for contributing!