NSFWPY 🔥 (nsfwpy-onnx v1.1.2)

High-performance, CPU-optimized Python NSFW image safety classification library powered by state-of-the-art Vision Transformer (ViT) models from Falcons AI and the ONNX Community using ONNX Runtime.

Classify static images (JPEG, PNG, WEBP) and Animated WebP / GIF / APNG formats into 5 canonical NSFW safety 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.

⚡ Why nsfwpy-onnx is Superior to Legacy Classifiers

🖥️ Cross-Platform System Model Caching

nsfwpy automatically detects host OS and environment permissions to cache models in optimal system directories:

• Linux / Servers: /etc/nsfwpy/models or /var/cache/nsfwpy/models
• Windows: C:\nsfwpy\models or C:\ProgramData\nsfwpy\models
• macOS: /Library/Caches/nsfwpy/models or ~/Library/Caches/nsfwpy/models
• Android / Termux / Mobile: /sdcard/.nsfwpy/models or $PREFIX/tmp/nsfwpy/models
• iOS / iPadOS / Tablets: ~/Documents/.nsfwpy/models
• Automatic Fallback: ~/.nsfwpy/models (if running as a non-root standard user without system write access)

📊 Performance & Preload Benchmarks

Tested on CPU (Intel/AMD multi-thread execution):

import nsfwpy

# Warm up model graph and CPU execution pools at app startup
nsfwpy.preload()

📥 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 default quantized ViT model (auto-downloads if missing)
model = nsfwpy.load_model()

# Classify static image or animated WebP / GIF
results = model.classify("sample.jpg", top_k=5)
print(results)
# Output:
# [
#   {'className': 'Neutral', 'probability': 0.9850},
#   {'className': 'Porn', 'probability': 0.0150}
# ]

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

2. Command Line Interface (CLI)

# Classify a local image file or URL using default nsfw_vit_quantized model
nsfwpy classify path/to/image.jpg

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

# Choose full precision nsfw_vit model
nsfwpy classify sample.jpg --model nsfw_vit

🧠 Supported Models

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

🙏 Credits & Acknowledgments

Special thanks to the open-source AI community and model creators:

• Falcons AI (falconsai): Creators of the high-accuracy Vision Transformer (ViT) model falconsai/nsfw_image_detection used as the core engine.
• ONNX Community (onnx-community): For converting, quantizing, and hosting the ONNX model suite at onnx-community/nsfw_image_detection-ONNX.

📜 License

MIT License