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.11,<3.16 - 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 (credentials come from the environment, see Secrets):
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
remotecv \
--backend=celery \
--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 |
| Image fetch timeout (seconds) | --loader-timeout |
IMAGE_LOADER_TIMEOUT |
20.0 |
| Image max size (bytes) | --loader-max-body-size |
IMAGE_LOADER_MAX_BODY_SIZE |
0 (no limit) |
| Image fetch User-Agent | --loader-user-agent |
IMAGE_LOADER_USER_AGENT |
remotecv/<version> |
| 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 bind address | --server-host |
HTTP_SERVER_HOST |
0.0.0.0 |
| 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 |
| Max image pixels | --max-image-pixels |
MAX_IMAGE_PIXELS |
89478485 (Pillow default, 0 disables) |
| Memcached hosts | --memcached-hosts |
MEMCACHED_HOSTS |
localhost:11211 |
Sentry events are tagged with the release remotecv@<version> unless the SDK
detects one on its own, for example from SENTRY_RELEASE, the git revision or
a platform variable such as HEROKU_SLUG_COMMIT.
Secrets
Every option that carries a secret also has an environment variable, and that is the form to use for it:
| Secret | Environment variable | CLI option (avoid) |
|---|---|---|
| Redis password | REDIS_PASSWORD |
--password |
| Redis Sentinel password | REDIS_SENTINEL_PASSWORD |
--sentinel-password |
| Redis Sentinel master password | REDIS_MASTER_PASSWORD |
--master-password |
| AWS secret access key | AWS_SECRET_ACCESS_KEY |
--key-secret |
A value passed on the command line is visible to every user on the host
through ps and /proc, and is often captured verbatim by process
supervisors and container orchestrators in their own logs. A process's
environment is only readable by its owner and root. Under an orchestrator,
inject the variables from its secret store rather than writing the values
into the manifest, where everyone who can read the manifest sees them.
Running --help with the variables set is safe: show_envvar prints the
variable name, never its value.
Built-in detectors
ImageProcessor ships with the following detector names:
facefeatureglassprofileall
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.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| remotecv-5.3.0.tar.gz | 961.7 kB | Without provenance | Details for remotecv-5.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| remotecv-5.3.0-py3-none-any.whl | Python 3 | none | any | Details for remotecv-5.3.0-py3-none-any.whl |
Total release size: 1.9 MB
Release files / remotecv-5.3.0.tar.gz
| Download URL | remotecv-5.3.0.tar.gz |
|---|---|
| Size | 961.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2d74a4a78dd90d9150dc258a42296b395ebecfdd65edf4ff4f6880ead36de764
|
|
BLAKE2b-256 checksum How to use checksums |
e6a452eb415559ccaec059a9879a60e7cef1a4109ce8feac61c280682fad584c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / remotecv-5.3.0-py3-none-any.whl
| Download URL | remotecv-5.3.0-py3-none-any.whl |
|---|---|
| Size | 970.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
37066d19443a4e707b16962006d496217dfc399e510f3ed313b856c35d3f0857
|
|
BLAKE2b-256 checksum How to use checksums |
1426cdd2e1d9c0da88fb523eed396f82300cd6cf1570d4c82ed6e9abea37410f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for remotecv 5.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.