Deploy InstantID: Open Source AI Avatar Generator

Your local InstantID server for AI avatars from one photo

By the end of this you’ll have InstantID running as a Gradio web UI on your machine. Drop one face photo, type a prompt, get identity-preserving avatars or stylized portraits – no training, no LoRA. Open-source InstantID from the InstantX team; main branch of the official repo (as of latest available code; notable commits through mid-2024 including Kolors work). Checkpoints still the 2024 InstantX/InstantID set on Hugging Face.

Full control. Offline. No cloud Space queue. That’s the point when Comfy nodes or hosted demos aren’t what you want.

System requirements for InstantID

InstantID sits on SDXL + ControlNet + IP-Adapter. VRAM decides whether a run finishes or dies.

CPU-only? Technically boots. Practically unusable. AMD/ROCm and Mac need community patches – out of scope here. On 12 GB cards, community reports (including InstantID issues) show shared-memory thrash or multi-minute steps unless you offload. 24 GB feels native. 12 GB is the floor people actually ship with.

Running your own face-locked generator changes how you iterate: no upload to a public Space, no waiting on someone else’s queue. That privacy trade is why the local path still matters even when demos look easier.

Official source and model download

Clone the real tree first – forks later if you need them:

git clone https://github.com/instantX-research/InstantID.git
cd InstantID

Checkpoints: InstantX/InstantID on HF (ControlNetModel config + safetensors, plus ip-adapter.bin). Face encoder is the pain point. The InsightFace antelopev2 zip on the old GitHub releases path 404s – README and issues (#230, #246 and earlier) confirm it. Manual fetch only.

mkdir -p models checkpoints
pip install huggingface_hub
python -c "
from huggingface_hub import hf_hub_download
hf_hub_download(repo_id='InstantX/InstantID', filename='ControlNetModel/config.json', local_dir='./checkpoints')
hf_hub_download(repo_id='InstantX/InstantID', filename='ControlNetModel/diffusion_pytorch_model.safetensors', local_dir='./checkpoints')
hf_hub_download(repo_id='InstantX/InstantID', filename='ip-adapter.bin', local_dir='./checkpoints')
"

Antelopev2: pull this HF mirror zip (or the Drive ID maintainers still paste in threads), unzip so models/antelopev2/*.onnx exists. gradio_demo/download_models.py tries automation; it often still needs the hand step. HF blocked? export HF_ENDPOINT=https://hf-mirror.com then retry.

Step-by-step installation

Clean env:

python -m venv venv
source venv/bin/activate # Windows: venvScriptsactivate
pip install -U pip
pip install -r gradio_demo/requirements.txt
# Official pins older torch (diffusers==0.25.1 era). Many stacks on current CUDA use:
# pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install onnxruntime-gpu insightface opencv-python

Force GPU InsightFace later if the provider list lies. Base SDXL pulls on first run – demo default is wangqixun/YamerMIX_v8; swap the path in code if you want another SDXL checkpoint.

After install: python -c "import insightface; print(insightface.__version__)". Then confirm CUDAExecutionProvider shows up before you open Gradio. Skips an hour of “why is this on CPU” debugging.

Launch:

python gradio_demo/app.py

Local bind, usually http://127.0.0.1:7860. Multi-ControlNet: python gradio_demo/app-multicontrolnet.py.

First-time configuration and VRAM survival

Defaults work for a smoke test. Want tighter ID match? Push controlnet_conditioning_scale and ip_adapter_scale toward 0.8-1.0 (README scale guidance). Back off if the face overpowers the prompt or colors blow out.

12 GB cards – add this right after the pipe is built (edit app.py or your infer script):

pipe.enable_model_cpu_offload()
pipe.enable_vae_tiling()

That’s the official VRAM tip. Tighter still: sequential_cpu_offload in some forks (slower). LCM-LoRA from latent-consistency/lcm-lora-sdxl (pytorch_lora_weights.safetensors) can cut steps to ~10 with guidance_scale near 0-1.

The catch with pure-source installs is almost never Diffusers itself. It’s the face-model path and which ONNX provider wins. Fix those two and the rest behaves like any SDXL pipeline.

Verify the install works

Open Gradio. Upload a clear frontal face (examples/ ships samples). Prompt: “professional headshot, studio lighting”. Hit generate.

Pass bar: identity matches the reference, style follows the prompt, no crash, nvidia-smi shows GPU use. Quick CLI: short infer snippet on the example image – output file writes, no OOM, no “Failed downloading”.

Common install errors and fixes

• RuntimeError: Failed downloading … antelopev2.zip – Expected. Manual zip → models/antelopev2. Do not wait on auto.
• ModuleNotFoundError: insightface / Cython / onnx – pip install Cython, reinstall insightface. Windows: prebuilt wheel matching your Python often beats building from source.
• OOM or 60s+/step crawl (CPU path) – pip uninstall onnxruntime; pip install onnxruntime-gpu. In FaceAnalysis, pass providers=[‘CUDAExecutionProvider’, ‘CPUExecutionProvider’] explicitly. Add the offload lines. Drop res toward 768; enable xformers if your torch build has it.
• Hub connect / base model missing – Pre-download SDXL or point a local path; hf-mirror if needed.

Same cluster of failures shows up across official Gradio threads and Comfy ports.

Docker alternative, upgrade, uninstall

docker run -d --gpus all -v /workspace -p 3000:3001 -p 7777:7777 -p 8888:8888 
 ghcr.io/ashleykleynhans/instantid:latest

Or ashleykza/instantid:latest. UI on host port 3000. Image stack (as published on that repo): Ubuntu 22.04, CUDA 12.4-class, newer Torch – check the ashleykleynhans/instantid-docker README for env vars and logs. Handy on RunPod-style boxes.

Upgrade: git pull, re-pip if requirements moved, refresh checkpoints only if new files appeared. No formal migration path; weights have stayed backward-compatible so far. Kolors adaptation landed mid-2024; treat extra weights as still evolving.

Cleanup: deactivate env, rm -rf InstantID venv, purge ~/.cache/huggingface, remove container/image and mounts. Models are fat – expect 10+ GB back.

Related once it runs: InstantStyle for stronger style lock, or native ComfyUI nodes if you want graphs instead of Gradio.

FAQ

Does InstantID need multiple photos or training?

No. One clear face image. Zero-shot is the design – see the arXiv paper (2401.07519).

Can I run it on 8-10 GB VRAM?

You can try sequential offload and a smaller canvas. Plan on multi-minute gens and the odd crash. Real floor most people report: 12 GB with model_cpu_offload. 24 GB stops feeling like a science project. Smoke-test one image before you batch.

Is commercial use allowed?

Code: Apache-2.0. InsightFace antelopev2 and the shipped InstantID checkpoints: research-only per their licenses and the project disclaimer on the project page/README. “I fine-tuned a client avatar farm” is not the same as “the Gradio demo ran.” Read both licenses and local rules before production. If you need clear commercial face rights, evaluate other stacks.

Start Gradio. If antelopev2 actually sits under models/, your first identity-locked avatar lands fast – usually under a minute once the pipes are warm.