NSFWPY 🔥 (nsfwpy-onnx)

High-performance, CPU-optimized Python 3.14 port of NSFWJS using ONNX Runtime.

Classify static images (JPEG, PNG, WEBP) and Animated WebP / GIF / APNG formats into 5 canonical NSFW categories (Drawing, Hentai, Neutral, Porn, Sexy).

🌟 Key Features

• 🐍 Python 3.14 Native: Fully compatible with Python 3.10+ and Python 3.14.
• 🎞️ Animated WebP & GIF Support: Keyframe sampling and frame-aggregated safety classification for Animated WebP, GIF, and APNG formats.
• ⚡ CPU Optimized: Powered by onnxruntime tuned for multi-threaded CPU execution with graph optimization.
• 📦 HuggingFace Auto-Download: Automatically downloads missing ONNX models from Hugging Face (expertskb/nsfwpy).
• 🪶 Ultra Lightweight: Minimal dependencies (numpy, pillow, onnxruntime, click). No heavy web servers required.
• 🛠️ CLI Tool Included: Classify images directly from your terminal.

📥 Installation

Install directly from PyPI:

pip install nsfwpy-onnx

Or install from GitHub:

git clone https://github.com/expertskb/nsfwpy-onnx.git
cd nsfwpy-onnx
python3.14 -m venv .venv
source .venv/bin/activate
pip install -e .

🚀 Quick Usage

1. Python Library Usage

import nsfwpy

# Load model (auto-downloads from HuggingFace if missing)
model = nsfwpy.load_model("mobilenet_v2")

# Classify static image or animated WebP / GIF
results = model.classify("sample.jpg", top_k=5)
print(results)
# Output:
# [
#   {'className': 'Neutral', 'probability': 0.6280},
#   {'className': 'Drawing', 'probability': 0.2822},
#   {'className': 'Sexy', 'probability': 0.0548},
#   {'className': 'Porn', 'probability': 0.0246},
#   {'className': 'Hentai', 'probability': 0.0104}
# ]

# Batch image classification
batch_results = model.classify_batch(["img1.jpg", "anim2.gif"])

2. Command Line Interface (CLI)

# Classify a local image file or URL
nsfwpy classify path/to/image.jpg

# Output formatted JSON
nsfwpy classify sample.jpg --json-out

# Choose a specific model architecture
nsfwpy classify sample.jpg --model inception_v3

🧠 Supported Models

1. 5-Category Models (NSFWJS Architecture)

2. Vision Transformer (ViT) Binary Models (SFW vs NSFW)

Powered by onnx-community/nsfw_image_detection-ONNX:

📂 Example Scripts Index

Professional production-ready scripts are included under examples/:

• examples/01_basic_classification.py: Local image classification.
• examples/02_url_classification.py: Remote image URL classification.
• examples/03_batch_classification.py: High-throughput batch benchmarking.
• examples/04_pil_and_bytes_classification.py: In-memory PIL and bytes buffer processing.
• examples/05_custom_model_and_threading.py: Model backbones & ONNX CPU thread tuning.
• examples/06_animated_webp_gif_classification.py: Animated WebP & GIF frame-aggregated classification.

Run any example using:

python examples/01_basic_classification.py

📜 License

MIT License