civitai-to-hf

Download models from CivitAI and upload them to HuggingFace Hub as proper model repositories — complete with README, code snippets, sample images, and metadata.

Features

• Works with any model type — LoRA, Checkpoints, Textual Inversion, VAE, ControlNet, and more
• Auto-generates README — YAML frontmatter, diffusers code snippets, trigger words, example prompts
• Downloads sample images — Extracts prompts, negative prompts, and generation parameters
• Smart base model mapping — SD 1.5, SDXL, Flux, SD 3.5, Pony, and many more
• NSFW-safe — All NSFW levels included by default
• Streaming uploads — Large model files are uploaded efficiently without loading into memory

Installation

npm install -g civitai-to-hf

Or run directly with npx:

npx civitai-to-hf https://civitai.com/models/144684

Prerequisites

Set these environment variables:

| Variable | Required | Description | |----------|----------|-------------| | HF_TOKEN | Yes | HuggingFace write token (get one here) | | CIVITAI_API_KEY | No | CivitAI API key (needed for gated/restricted models) |

Usage

# Basic: download + upload
civitai-to-hf https://civitai.com/models/144684

# Specify exact HF repo name
civitai-to-hf https://civitai.com/models/144684 --hf-repo myuser/my-sweet-lora

# Private repo
civitai-to-hf https://civitai.com/models/144684 --private

# Download only (skip HF upload)
civitai-to-hf https://civitai.com/models/144684 --no-upload --download-dir ./my-model

# Specify a particular version
civitai-to-hf "https://civitai.com/models/144684?modelVersionId=123456"

All Options

| Option | Description | |--------|-------------| | --hf-repo <repo> | Target HuggingFace repo ID (auto-generated by default) | | --private | Make the HF repo private (default: public) | | --civitai-key <key> | CivitAI API key (default: CIVITAI_API_KEY env) | | --hf-token <token> | HuggingFace write token (default: HF_TOKEN env) | | --download-dir <dir> | Local directory to save files (default: temp dir) | | --no-upload | Download only, skip HuggingFace upload | | --max-images <n> | Maximum sample images to download (default: 20) |

Input Formats

The tool accepts many input styles:

https://civitai.com/models/144684              # Model page URL
https://civitai.com/models/144684?modelVersionId=123456  # Specific version
https://civitai.red/models/1120962              # Mirror URL
https://civitai.com/api/download/models/28907   # Download API URL
144684                                          # Plain model ID

What It Does

1. Fetches metadata from CivitAI REST API
2. Selects version — latest or specific
3. Downloads model file — primary .safetensors + any additional files
4. Downloads sample images — up to --max-images with generation metadata
5. Generates README.md — with YAML frontmatter, description, trigger words, and diffusers code
6. Saves metadata — civitai_metadata.json with full source info
7. Creates HF repo — public or private
8. Uploads everything — single batch upload via streaming

Supported Model Types

| CivitAI Type | HF Repo Type | |---|---| | Checkpoint, LoRA, LoCon, DoRA, VAE, ControlNet, TextualInversion, Hypernetwork, Upscaler, MotionModule | model | | Wildcards, Workflows | dataset |

License

MIT