CEVTUO · BLENDER TOOLING

Cevtuo-Blendergate

One gate for every headless Blender job on your machine.
Concurrency follows live CPU pressure — the queue stays in control.

一台机器上所有 headless Blender 作业的串行闸门：并发按整机 CPU 压力动态决定，其余排队，先来先跑。

author: cevtuo · MIT · macOS & Linux · Python 3.9+

$ curl -fsSL https://github.com/cevtuocjw/blendergate/releases/latest/download/install.sh | sh
Download blq.pysingle file · zero dependencies View on GitHubsource · releases · issues

GitHub downloads can be slow in mainland China — ghproxy.net · gh-proxy.com · ghfast.top 镜像只是把 GitHub 流量中转一下，内容完全一致；介意的话请用官方链接。

blq · sample output（示例输出）
$ blq render scripts/g39-goti-g36.py -- --res 700
[blq 10:42:07] 状态页：http://127.0.0.1:8132/  （随时重开：blq open）
[blq 10:42:07] 排队中：g39-goti-g36.py（动态并发，上限 5）
[blq 10:42:09] 开始：g39-goti-g36.py · 槽位 1 · 等待 2s

$ blq status
运行中：
  ● 槽位 1  g39-goti-g36.py        4m12s
  ● 槽位 2  g39-ysl-y-col-46.py     2m38s
  ● 槽位 3  blender-g39-djula-d22.py  1m44s
排队中：
  · blender-g238.py  已等 26s
并发：动态并发 1–5 · 运行 3 件 · 整机 CPU 71%
⚠ 绕过闸门的 headless Blender 1 个：
  ! pid 48213   98.4%   3m20s  blender -b --factory-startup -P ...
  → 这些就是互相抢核的元凶：blq kill-strays --yes

同一份队列，终端和状态页看的是同一个东西。

As many as the machine can take

The gate samples CPU and memory and admits the next job only when there is room, up to BLQ_MAX_SLOTS (default half your cores). Prefer a fixed number? Set BLQ_SLOTS.

Every window, one queue

Shells, editors and agents all share ~/.cache/blender-queue. No daemon, no config, no per-project setup.

Never the same job twice

If the same script is already running or queued, the new submission is skipped. Change the script — or pass --force — to run it again.

Strays get named

Headless Blender processes that bypassed the gate are listed with pid, CPU and elapsed time. blq kill-strays --yes stops them.

A status page that sleeps

It starts with the first job and exits after five idle minutes. When the tab is hidden it stops polling entirely — no more endless 3-second reloads.

One file, zero dependencies

Pure Python standard library. Read it, audit it, vendor it. MIT licensed.

Why a gate?

A gate turns "however many windows I happen to have open" into a measured decision. It watches real CPU pressure and admits the next job only when the machine has room. You get a predictable pipeline, and the number of concurrent slots is a setting — not a guess.

1shared queue for every window
1–5dynamic slots, tuned to CPU pressure
85%default CPU target before it holds

Installation

macOS & Linux · click to expand · 点开看安装步骤

1 · One line

  1. Run the installer: 
    curl -fsSL https://github.com/cevtuocjw/blendergate/releases/latest/download/install.sh | sh
    装到 ~/.local/bin/blq；用 BLQ_BIN=$HOME/bin 可以换目录。
  2. Make sure ~/.local/bin is in your PATH: 
    export PATH="$HOME/.local/bin:$PATH"
    安装脚本发现 PATH 里没有它时会提醒你。
  3. Verify: 
    blq --version
blq status

2 · Requirements

  1. Python 3.9+ — macOS system Python or Homebrew both work.
  2. Blender — detected at /Applications/Blender.app, ~/Applications/Blender.app, or on PATH. Override with BLENDER=/path/to/Blender.
  3. macOS or Linux. Windows is not supported yet (the queue relies on fcntl file locks).

3 · Manual install

  1. Download the single file: 
    curl -fsSL -o blq \
  https://github.com/cevtuocjw/blendergate/releases/latest/download/blq.py
chmod +x blq
mv blq ~/.local/bin/blq
  2. Or grab the tarball from the latest release.

4 · First run

  1. Queue a render instead of calling Blender directly: 
    blq render scripts/xxx.py -- --res 700
    -b --factory-startup -P 会自动带上。
  2. Open the live queue: 
    blq open      # http://127.0.0.1:8132/
  3. Tune the gate if you want: 
    BLQ_MAX_SLOTS=6 blq render scripts/xxx.py   # 上限 6
BLQ_CPU_TARGET=0.9 blq render scripts/xxx.py # 允许更满
BLQ_SLOTS=3 blq render scripts/xxx.py        # 固定 3 件
  4. Uninstall: rm ~/.local/bin/blq and, if you want, rm -rf ~/.cache/blender-queue.