Homebrew bottle install: ModuleNotFoundError: No module named 'vllm_swift'

[heykb]

Describe the bug
After installing vllm-swift via Homebrew bottle (brew install TheTom/tap/vllm-swift), running vllm-swift serve fails immediately with:

/Users/a1-6/.vllm-swift/venv/bin/python3: Error while finding module specification for 'vllm_swift.cli' (ModuleNotFoundError: No module named 'vllm_swift')

To Reproduce

brew install TheTom/tap/vllm-swift
vllm-swift serve ~/models/Qwen3.6-27B-ConfigI-MLX \
    --served-model-name qwen3.6-27b \
    --max-model-len 40960 \
    --enable-auto-tool-choice --tool-call-parser hermes \
    --additional-config '{"kv_scheme": "turbo4", "kv_bits": 4}'

Environment

• macOS (Apple Silicon, arm64)
• Install method: Homebrew bottle (not from source)
• vllm-swift version: 0.6.1
• vLLM version: 0.19.1

Root Cause Analysis

I traced the issue and found a mismatch between the Formula design and the actual bottle contents:

1. The Formula defines a managed venv in def install:

   venv_dir = libexec/"venv"
   system "python3", "-m", "venv", venv_dir
   # ... install torch, vllm, and the plugin
   system venv_pip, "install", "-q", "-e", libexec

2. But the bottle does NOT contain this managed venv:

   $ ls /opt/homebrew/Cellar/vllm-swift/0.6.1/libexec/venv/bin/python3
   ls: .../venv/bin/python3: No such file or directory

3. The bash wrapper falls back to ~/.vllm-swift/venv, and its _ensure_venv() function installs vllm>=0.19.0 but never installs the vllm_swift plugin itself.

4. Result: the fallback venv has vllm but not vllm_swift, so python3 -m vllm_swift.cli crashes.

Verification

# fallback venv has vllm but NOT vllm_swift
$ /Users/a1-6/.vllm-swift/venv/bin/python3 -c "import vllm; print(vllm.__version__)"
0.19.1

$ /Users/a1-6/.vllm-swift/venv/bin/python3 -c "import vllm_swift"
ModuleNotFoundError: No module named 'vllm_swift'

Workaround (confirmed working)

cd /opt/homebrew/Cellar/vllm-swift/0.6.1/libexec
/Users/a1-6/.vllm-swift/venv/bin/pip install -e .

After this, vllm-swift serve works correctly.

Suggested Fixes

Option A (preferred): Ensure the Homebrew bottle includes the managed libexec/venv. If Homebrew bottling excludes venvs, consider installing the plugin to the system Python site-packages instead.

Option B: Fix the bash wrapper's _ensure_venv() fallback to also install the plugin from the Cellar:

"$VENV_DIR/bin/pip" install -q -e "$PREFIX/libexec"

Option C: If the managed venv exists, use it; otherwise during fallback setup, install both vllm and vllm-swift.

---

Happy to test any fix or provide more logs. Thanks for the great project!