Skip to content

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.

  1. 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.
  2. 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.
  3. 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

  1. Homebrew packages:

    brew install ollama uv
    
  2. Ollama and an LLM (~8GB download):

    brew services start ollama
    ollama pull gemma3:12b
    
  3. Python environment, from the project folder:

    uv sync
    
  4. 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.
  5. Check the connection to Draw Things:

    uv run python scripts/probe.py
    

    It checks the API answers and lists which models it found and which are missing; it renders nothing (add --render for 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

  1. Copy or clone the project folder, and copy your data folder if you want your history. Don't copy .venv/; setup.sh rebuilds it.
  2. Run scripts/setup.sh and follow the Draw Things steps it prints.
  3. 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 uv command fails with Abort trap: 6 or Library not loaded: the .venv folder was copied from elsewhere. Run rm -rf .venv && uv sync (or just scripts/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:LISTEN shows what. Or use a different --port.
  • Generate fails and Draw Things never gets a job, with a 400 unknown model key or not installed in Draw Things error: you changed config/models.yaml since starting the server. Restart it.
  • All model chips are greyed out: the app can't find Draw Things' model folder. Check draw_things.models_dirs in config/models.yaml, then refresh the page.
  • --loras says CIVITAI_TOKEN is not set although it's in .env: check the line isn't commented out and is a plain KEY=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 set DRAFTPOOL_DATA_DIR correctly. 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_timeout in config/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.