RemoteCV

RemoteCV is a background worker for OpenCV-based image detection. It is most commonly used by Thumbor to offload face and feature detection, but it can also be integrated into any system that needs asynchronous image analysis with cached results.

The worker supports:

Redis + PyRes as the default queue backend
Celery with Amazon SQS
Built-in OpenCV detectors for face, profile, glasses, feature, and combined detection
Pluggable image loaders, metrics backends, and result stores
Optional HTTP healthcheck endpoint

Requirements

Python >=3.10,<3.15
Redis for the default backend and default result store
OpenCV runtime dependencies supported by opencv-python-headless

If you want to run the Celery backend, install celery in the same environment. The CLI supports it, but Celery is not part of the core runtime dependencies installed by pip install remotecv.

Installation

Install RemoteCV from PyPI:

pip install remotecv

For local development:

git clone https://github.com/thumbor/remotecv.git
cd remotecv
python -m venv .venv
. .venv/bin/activate
pip install -U pip
make setup
pre-commit install

Running RemoteCV

The default worker uses the PyRes backend and connects to Redis on localhost:6379:

remotecv

You can also use the Makefile shortcut:

make run

Common examples

Start the default worker with a healthcheck endpoint:

remotecv --with-healthcheck --server-port=8888

Connect to a different Redis instance:

remotecv --host=redis.internal --port=6379 --database=1

Use Redis Sentinel mode:

remotecv \
  --redis-mode=sentinel \
  --sentinel-instances=sentinel-1:26379,sentinel-2:26379 \
  --master-instance=mymaster

Run with Celery + SQS:

remotecv \
  --backend=celery \
  --region=us-east-1 \
  --key-id="$AWS_ACCESS_KEY_ID" \
  --key-secret="$AWS_SECRET_ACCESS_KEY" \
  --celery-commands=worker \
  --celery-commands=--loglevel=INFO

Configuration

RemoteCV can be configured either by CLI flags or environment variables. These are the options you are most likely to use:

Purpose	CLI option	Environment variable	Default
Queue backend	`--backend`	`BACKEND`	`pyres`
Redis host	`--host`	`REDIS_HOST`	`localhost`
Redis port	`--port`	`REDIS_PORT`	`6379`
Redis mode	`--redis-mode`	`REDIS_MODE`	`single_node`
Redis TTL for stored detections	`--redis-key-expire-time`	`REDIS_KEY_EXPIRE_TIME`	`1209600`
Worker timeout	`--timeout`	`DETECTOR_TIMEOUT`	unset
Worker TTL	`--worker-ttl`	`WORKER_TTL`	unset
Result store backend	`--store`	`DETECTOR_STORAGE`	`remotecv.result_store.redis_store`
Image loader	`--loader`	`IMAGE_LOADER`	`remotecv.http_loader`
Metrics backend	`--metrics`	`METRICS_CLIENT`	`remotecv.metrics.logger_metrics`
Log level	`--level`	`LOG_LEVEL`	`debug`
Log format	`--format`	`LOG_FORMAT`	Python logging default for this project
Healthcheck port	`--server-port`	`HTTP_SERVER_PORT`	`8080`
Enable healthcheck	`--with-healthcheck`	`WITH_HEALTHCHECK`	disabled
Sentry DSN	`--sentry-url`	`SENTRY_URL`	unset
Clear image metadata	`--clear-image-metadata`	`CLEAR_IMAGE_METADATA`	disabled
Memcached hosts	`--memcached-hosts`	`MEMCACHED_HOSTS`	`localhost:11211`

Built-in detectors

ImageProcessor ships with the following detector names:

face
feature
glass
profile
all

You can combine detectors with + in queued jobs, for example face+profile.

Result storage

By default, detection results are stored in Redis using the key pattern thumbor-detector-<key>.

RemoteCV also includes a Memcached-backed result store implementation in remotecv.result_store.memcache_store. If you use it, make sure the appropriate Memcached client dependency is installed in your environment.

Development workflow

Run unit tests:

make unit

Run the full local test flow with Redis containers:

make test

Start and stop the test Redis/Sentinel stack manually:

make run-redis
make stop-redis

Run code quality checks:

make black
make flake
make pylint
make lint

Project layout

remotecv/
  worker.py             CLI entry point and runtime configuration
  image_processor.py    Detector orchestration
  image.py              Image parsing and normalization
  http_loader.py        Remote image loading
  unique_queue.py       PyRes worker implementation
  celery_tasks.py       Celery/SQS integration
  detectors/            OpenCV detectors and cascade files
  metrics/              Metrics backends
  result_store/         Detection result store implementations
tests/
  fixtures/             Sample images and Redis/Sentinel fixtures

Security

Please do not report security issues in public issues. See SECURITY.md for the recommended disclosure process.

Metadata

Release files for remotecv 5.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for remotecv 5.2.0
File	Size	Uploaded
remotecv-5.2.0.tar.gz	951.8 kB	Mar 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for remotecv 5.2.0
File	Interpreter	ABI	Platform	Reset
remotecv-5.2.0-py3-none-any.whl 966.5 kB Mar 16, 2026	Python 3	none	any	Details

Total release size: 1.9 MB

Release files / remotecv-5.2.0.tar.gz

Download URL	remotecv-5.2.0.tar.gz
Size	951.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`f21b17d096a646968f8287122b621f2f6f83b7dc8300c165fe748a0ac359651f`
BLAKE2b-256 checksum How to use checksums	`879662d99d5ea0b648e3dd2cfb872b25459843fe2f508acaadca864b48a910f2`
Upload date	Mar 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / remotecv-5.2.0-py3-none-any.whl

Download URL	remotecv-5.2.0-py3-none-any.whl
Size	966.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`035c263059bf0c57d2207af8d25384b8fa5c8b32b34087d494261551f244b017`
BLAKE2b-256 checksum How to use checksums	`5e6e1ebc4436c1b2dcf0a667ddba4ee2c043ab572221d5dcb9f0e89471d57776`
Upload date	Mar 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`