NSFWPY 🔥 (nsfwpy-onnx)

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

Classify images into 5 canonical NSFW categories (Drawing, Hentai, Neutral, Porn, Sexy) with fast CPU inference, zero GPU requirement, HuggingFace auto-downloading, and a clean Python API + CLI.

🌟 Key Features

• 🐍 Python 3.14 Native: Fully compatible with Python 3.10+ and Python 3.14.
• ⚡ 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 single image (File path, URL, bytes, or PIL Image)
results = model.classify("path/to/image.jpg", top_k=5)
print(results)
# Output:
# [
#   {'className': 'Neutral', 'probability': 0.85231},
#   {'className': 'Drawing', 'probability': 0.08412},
#   {'className': 'Sexy', 'probability': 0.04123},
#   {'className': 'Porn', 'probability': 0.01211},
#   {'className': 'Hentai', 'probability': 0.01023}
# ]

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

2. Command Line Interface (CLI)

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

# Output formatted JSON
nsfwpy classify https://example.com/sample.jpg --json-out

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

🧠 Supported Models

📂 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.

Run any example using:

python examples/01_basic_classification.py

📜 License

MIT License