Start here:
neurobrix doctor
It checks PATH, the PyTorch build, Triton, NVIDIA GPUs and drivers, and prints the fix for a blocking problem. Exit code 0 means none found, 1 means problems were listed. It does not check AMD or Apple devices.
neurobrix: command not foundThe script directory is not on PATH. Activate your environment (source nbx/bin/activate). If the install worked but the shell still cannot find the command, neurobrix doctor (run by its full path, in the environment's bin/ directory) prints the exact PATH line to add.
externally-managed-environment (PEP 668)Your distribution forbids system-wide pip install. Use a virtual environment:
python3 -m venv nbx && source nbx/bin/activate
pip install neurobrix
On Debian and Ubuntu install python3-venv first. Or use pipx install neurobrix.
doctor reports a blocking problem: a GPU is present and the installed PyTorch cannot use it. Its fix:
pip install --force-reinstall torch --index-url https://download.pytorch.org/whl/cu124
doctor prints cu121 for a compute capability 7.0 card; for V100 prefer cu126 (next entry). More in Install by hardware.
cu128, cu129, cu130 and cu132 wheels do not include sm_70. doctor shows the mismatch between your GPU's sm_XY and the architectures PyTorch was built for. Reinstall:
pip install --force-reinstall torch --index-url https://download.pytorch.org/whl/cu126
pip install neurobrix pulls the CUDA build of PyTorch even on a machine without a GPU. For a CPU-only install:
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install neurobrix
ERROR: not enough disk for this importAn import is refused unless free space is at least about twice the archive size plus 2 GiB (the archive is kept next to the extracted copy). Free space first. --no-keep deletes the archive after extraction, which reduces what stays on disk. neurobrix clean --store removes old archives and neurobrix clean --cache extracted models.
Connection lost during download ... re-run the same command to resume
Run the same neurobrix import again. The partial file (.part in ~/.neurobrix/store/) is kept and the download continues from where it stopped. If the server cannot resume, it restarts from zero.
| Status / code | Meaning | What to do |
|---|---|---|
401 LICENSE_LOGIN_REQUIRED |
Gated model, no acceptance sent | Accept in the CLI or on the web: Licences |
403 LICENSE_NOT_ACCEPTED |
Signed in, licence not accepted | Accept on the model page |
403 MODEL_HIDDEN |
The model was withdrawn | Check the model page for the reason |
403 GRANT_INVALID |
The download link expired (links last one hour) or is malformed | Run the import again for a fresh link |
| 404 | Slug not found | Check spelling and case: neurobrix hub --search <name> |
503 ARTIFACT_UNAVAILABLE / ARTIFACT_CHANGED |
The hub cannot serve that file right now | Retry later; if it persists, report it |
ERROR: unknown category (exit 2)ERROR: unknown category 'AUDIO'
Valid categories: LLM, CODE, VLM, MULTIMODAL, TTS, STT, AUDIO_LLM, IMAGE, UPSCALER, VIDEO
Use one of the listed values. ERROR: Cannot connect to registry is a different, real network failure (exit 1).
A serving daemon is already runningA model is being served. Either use it (neurobrix run --prompt "..." without --model), or stop it:
neurobrix stop
neurobrix serve prints Daemon already running (PID n) for the same reason. Only one task runs at a time.
ERROR: --model is required when no daemon is running.Pass --model <Model> (the bare name, not org/Model), or start a daemon with neurobrix serve.
ZERO FALLBACK messagesThe engine refuses to guess. The message names what is missing:
ZERO FALLBACK: family 'upscaler' requires --input-image. Provide it on the command line.
ZERO FALLBACK: output extension '.x' incompatible with family ... Expected '.y'
Add the flag it names, or fix the --output extension. Rationale: ZERO principles.
ERROR: Only one execution mode flag can be passed at a time. — use only one of --compiled, --sequential, --triton, --triton-sequential.ERROR: Invalid model reference — import needs org/Model.Model '<org/name>' not found on registry. — check the slug in the catalogue.ERROR: Specify --store, --cache, or --all — neurobrix clean needs one of them.sudo that is root's.| Code | Meaning |
|---|---|
| 0 | Success (doctor: no blocking problem) |
| 1 | An error (ERROR: ...), an unexpected error (UNEXPECTED ERROR with a traceback), or doctor found problems |
| 2 | hub: the registry rejected the request, for example an unknown category |
| 130 | Interrupted with Ctrl-C |
neurobrix run exits with the non-zero status of the run. The exit code of validate is not documented yet.
Run NBX_DEBUG=1 neurobrix <command> for more output and report the issue with the output of neurobrix doctor --json.
CLI reference · Install by hardware
© 2025–2026 Hocine Benkelaya. NeuroBrix engine released under the Apache License 2.0.
Developed by Hocine Benkelaya · Supported and funded by Neural Network Holding Ltd · Commercial distribution by WizWorks OÜ