Setup in full¶
The short version is in the README. This page covers the rest: what the setup script does, installing by hand, the models it supports, where your data lives, updating, moving to another Mac, and troubleshooting.
What scripts/setup.sh does¶
With no options, it installs the Homebrew packages, starts Ollama, sets up the Python environment and downloads the Real-ESRGAN upscaler used by 2x fast. It then lists the models to install in Draw Things and where to get each one. It stops early with a clear message if you're not on an Apple Silicon Mac.
Model downloads are optional:
| option | downloads |
|---|---|
--llms |
the two Ollama models, gemma3:12b and qwen3-vl:8b (~14GB) |
--loras |
the two speed LoRAs that come from Civitai, Anima Turbo and Qwen Image Turbo (~1.3GB) |
./scripts/setup.sh # tools + upscaler
./scripts/setup.sh --llms # + the two Ollama models
./scripts/setup.sh --llms --loras # + the Civitai speed LoRAs
--loras needs a Civitai API key: put it in CIVITAI_TOKEN, either in .env
or exported in your shell. Create one at civitai.com → Account settings → API
Keys. The same key is used by Publish…, so it's worth setting anyway.
Neither option is required: the models in Draw Things' own catalogue are
enough to use the app.
The video model is never downloaded by the script. Draw Things downloads and converts it itself; the script just tells you what to look for.
Before downloading anything, the script checks you have enough free disk space and stops if you don't. Importing a model into Draw Things temporarily needs space for two copies, so leave some room to spare.
The models¶
From Draw Things' catalogue: FLUX.3 klein, FLUX.2 klein, FLUX.1 schnell, Z-Image Turbo, Krea 2 Turbo, Juggernaut XL Ragnarok, Qwen Image and Qwen Image Edit. The setup script lists them by the names Draw Things' search box finds them under, and they need no Civitai account.
From Civitai, the app supports classes of model rather than a list of them. Any full checkpoint of these base models works:
| class | Civitai's "Base Model" | what it is |
|---|---|---|
| Illustrious | Illustrious | SDXL-architecture anime models trained on Danbooru tags |
| Anima | Anima | Cosmos 2.5 2B anime models, also Danbooru-tagged |
| SDXL | SDXL 1.0 | photographic and general SDXL models |
Download the checkpoint from its Civitai page while logged in, import the
.safetensors in Draw Things (Models list → Manage → Import Model) and
refresh the page: it appears in the composer, set up for its class. Some
versions were measured for the app one by one; the app recognises those by
their weights, whatever the file is called, and gives them their own settings
and their Civitai version for the credit when you publish. Details, and what
to do when the class is guessed wrong, are in
Adding a model.
Your models live in config/models.private.yaml, which updates never touch.
The video models¶
Optional, for Animate. Install MiniMax H3, the recommended one; add FusionX only if you want the lighter alternative.
| MiniMax H3 + Turbo | Wan 2.1 FusionX | |
|---|---|---|
| a 2-second clip | about 6 min | about 12 min |
| a 5-second clip | about 14 min | about 30 min |
| frame rate | 24 fps | 16 fps |
| a pose change (a seated figure stands up) | worked when tried | doesn't |
| disk | 54GB, and 0.8GB for the LoRA | 17GB |
Times are on an M4 Pro with 48GB.
MiniMax H3¶
It needs Draw Things 26.0910 or later, so update it from the App Store first.
- In Draw Things' model manager, search for MiniMax H3 and download MiniMax H3 (4-bit S). It fetches its text encoder and video decoder with it, 54GB in all. Don't take an entry marked [ref2va] or FastH3 Omni: those use your picture as a character reference for a new shot rather than as the first frame.
- Download the Turbo LoRA, which makes H3 about four times faster at the same quality:
minimax_h3_turbo_v4_step600_ema.safetensors(0.8GB, Hugging Face, no account needed), or let the setup script fetch it with./scripts/setup.sh --video-lora. - Import it in Draw Things: LoRA list → Manage → Import LoRA.
Animate hides H3 until both the model and the LoRA are installed. On a 48GB Mac, close other heavy apps while a clip renders.
Wan 2.1 FusionX¶
Search Draw Things' model manager for Wan 2.1 14B I2V FusionX (17GB); it downloads and converts it for you. No LoRA needed.
What each can and can't do is in the guide.
Manual install¶
-
Homebrew packages:
brew install ollama uv -
Ollama and an LLM (~8GB download):
brew services start ollama ollama pull gemma3:12b -
Python environment, from the project folder:
uv sync -
Draw Things: install it from the Mac App Store (free), then:
- In Settings, turn on API Server, protocol HTTP, port 7860. Check this again after restarting the app, as it sometimes turns off.
- Download models in the model manager. Start with Z-Image Turbo (~6GB, and the fastest here), then add FLUX.2 klein 9B for a second look to compare. Add Qwen Image Edit 2511 for editing by instruction and Combine, and MiniMax H3 for Animate.
- FLUX.1 schnell works but is mostly redundant with FLUX.2 klein and Z-Image Turbo.
- Qwen Image 2512 is much slower than the rest (minutes per image). Use it for a single image you care about, not for trying things out.
- Download an upscaler under Official Upscalers: 4x UltraSharp (~34MB). Upscale is disabled until one is installed.
- Import any Illustrious, Anima or SDXL checkpoints you want from Civitai (see the models).
- Add the LoRAs for the models you installed.
-
Check the connection to Draw Things:
uv run python scripts/probe.pyIt checks the API answers and lists which models it found and which are missing; it renders nothing (add
--renderfor one tiny test image). Nothing needs editing: the app finds each model's file whatever variant you downloaded, and hides the ones that aren't there.
LoRAs¶
Small add-on files that make certain models several times faster. All are optional, and you only need the ones for models you have.
| LoRA | size | for | what it does | where to get it |
|---|---|---|---|---|
| Qwen Image Edit 2511 Lightning 4-Step v1.0 | 0.8GB | Qwen Edit | Edits in about 1.5 minutes instead of 5 | Draw Things' LoRA list · source |
| Wuli-art Qwen-Image-2512 Turbo (4 steps) | 1.1GB | Qwen Image 2512 | Finished images in under a minute instead of 3.5 | Civitai, then LoRA list → Manage → Import LoRA. Not the "Qwen Image 2512 Lightning" in Draw Things' list, which doesn't work here |
| Anima Turbo LoRA v0.2 | 0.14GB | Anima models | Finished images in about a minute instead of six; changes the look | Civitai, then LoRA list → Manage → Import LoRA |
setup.sh --loras downloads the two Civitai LoRAs for you. Once
installed they're switched on; you can turn each one off in the ⚙ dialog.
The guide explains the trade-offs.
Where your data lives¶
data/ holds the only things an install can't rebuild: draftpool.db (every
session, prompt, seed and setting) and sessions/, which holds every image and
clip. Everything else comes back from the code and scripts/setup.sh.
It defaults to data/ inside the project folder. Move it somewhere else so
an update can never touch it:
mkdir -p ~/draftpool-data
mv data/* ~/draftpool-data/
Then set DRAFTPOOL_DATA_DIR in .env to the new location. .env is created
by setup.sh on its first run and is never touched by updates:
DRAFTPOOL_DATA_DIR=/Users/you/draftpool-data
#CIVITAI_TOKEN=
Use a full path (~ works). A shell variable overrides .env, which is handy
for a one-off run:
DRAFTPOOL_DATA_DIR=~/other-pool uv run uvicorn app.main:app --port 8500
When the server starts, it prints which data folder it opened:
data directory: /Users/you/draftpool-data (37 session(s)); override with DRAFTPOOL_DATA_DIR
Check this after an update or a move. If DRAFTPOOL_DATA_DIR is wrong, the
app simply starts with an empty history. Nothing is lost: set the path
correctly and restart.
Updating¶
The database upgrades itself on the first start of a new version, so there's no separate migration step.
| comes with an update? | what to do | |
|---|---|---|
app/, static/, scripts/, tests/ |
yes | nothing |
config/models.yaml |
yes, but you may have edited it | keep a copy of your changes, see below |
config/models.private.yaml |
no, it's yours | nothing: your own models stay |
.venv/ |
no | setup.sh rebuilds it |
tools/realesrgan |
no | setup.sh downloads it again if it's missing |
data/ |
no | keep it, see Where your data lives |
.env |
no | keep it |
If you cloned the repository:
git diff config/models.yaml # see your own changes first
git pull
./scripts/setup.sh
uv run uvicorn app.main:app --port 8500
data/ and tools/ are ignored by git, so a pull never touches them.
If you downloaded a zip: unpack the new version into a new folder, never
over the old one. Copy .env across (and data/ if it's still inside the old
folder), run ./scripts/setup.sh, start the server and check the data folder
line. Then delete the old folder.
config/models.yaml is the one file where an update can lose your changes.
Put a model of your own in config/models.private.yaml instead, ideally with
the add script, and an update can't touch it. If
you've edited models.yaml itself, keep a copy before updating and compare
afterwards:
cp config/models.yaml ~/models.yaml.mine
# ...update...
diff ~/models.yaml.mine config/models.yaml
A model an update stops shipping stays yours. If it's still installed in
Draw Things, the server adds it back to config/models.private.yaml the first
time it starts after the update. It keeps its old name, its settings and your
pictures made with it, and the server's log says which models it kept. If you
delete such an entry, it stays deleted. This needs the git clone, because the
old settings come from its history. After a zip update, add the model back with
scripts/add_civitai_model.py and its Civitai version id; if its settings
were measured here, you get exactly those again.
There's no way to downgrade the database. To go back to an older version, go
back to a copy of data/ from before the update too.
Moving to another Mac¶
- Copy or clone the project folder, and copy your
data folder if you want your history. Don't copy
.venv/;setup.shrebuilds it. - Run
scripts/setup.shand follow the Draw Things steps it prints. - Models: downloading the catalogue models again in Draw Things is usually easiest. Copy the ones you imported by hand (the Civitai models and LoRAs) from Draw Things' model folder:
~/Library/Containers/com.liuliu.draw-things/Data/Documents/Models
If you use a custom model folder, make sure it's listed under
draw_things.models_dirs in config/models.yaml.
The app matches model files automatically, even if they're a different
quantisation (q8p, i8x, f16). A model it can't find shows as a greyed-out
chip.
Troubleshooting¶
- Every
uvcommand fails withAbort trap: 6orLibrary not loaded: the.venvfolder was copied from elsewhere. Runrm -rf .venv && uv sync(or justscripts/setup.sh). - Port already in use (8500 for this app, 7860 for Draw Things, 11434 for
Ollama): something else is using it, or an old copy is still running.
lsof -iTCP:8500 -sTCP:LISTENshows what. Or use a different--port. - Generate fails and Draw Things never gets a job, with a
400 unknown model keyornot installed in Draw Thingserror: you changedconfig/models.yamlsince starting the server. Restart it. - All model chips are greyed out: the app can't find Draw Things' model
folder. Check
draw_things.models_dirsinconfig/models.yaml, then refresh the page. --lorassaysCIVITAI_TOKENis not set although it's in.env: check the line isn't commented out and is a plainKEY=value.- A Civitai download fails or times out: download from the LoRA pages in your browser instead.
- Your sessions disappeared after an update or move: the app opened a
different data folder. Check the
data directory:line printed at startup and setDRAFTPOOL_DATA_DIRcorrectly. See Where your data lives. - The header says Draw Things down, or the connection is refused: Draw Things isn't open, or its API Server setting switched itself off, often after an app update. Open it and turn the setting back on.
- The header says Ollama down: start it with
brew services start ollama. Enrich, From image…, Finalize+ and Improve with LLM need it; your own prompt still renders without it. - "no reply within 300s" from the LLM: the model took too long, often
because it was still loading. Press Retry. If it keeps happening, choose
a smaller model, or raise
llm.request_timeoutinconfig/models.yaml. - Running out of disk during downloads: the script checks space first, but it only downloads the LLMs (about 14GB) and the LoRAs (about 2GB together). Most of the disk goes on the models Draw Things downloads itself; setup prints each one's size, and importing one briefly needs room for two copies.
- Upscale is disabled with "no upscaler installed": download 4x UltraSharp in Draw Things under Official Upscalers.