Instructions to use mlx-community/gemma-4-e4b-it-OptiQ-4bit with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use mlx-community/gemma-4-e4b-it-OptiQ-4bit with MLX:

# Make sure mlx-lm is installed
# pip install --upgrade mlx-lm

# Generate text with mlx-lm
from mlx_lm import load, generate

model, tokenizer = load("mlx-community/gemma-4-e4b-it-OptiQ-4bit")

prompt = "Write a story about Einstein"
messages = [{"role": "user", "content": prompt}]
prompt = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True
)

text = generate(model, tokenizer, prompt=prompt, verbose=True)

Notebooks
Google Colab
Kaggle
Local Apps Settings
LM Studio

How to use mlx-community/gemma-4-e4b-it-OptiQ-4bit with Pi:

Start the MLX server

# Install MLX LM:
uv tool install mlx-lm
# Start a local OpenAI-compatible server:
mlx_lm.server --model "mlx-community/gemma-4-e4b-it-OptiQ-4bit"

Configure the model in Pi

# Install Pi:
npm install -g @mariozechner/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "mlx-lm": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "mlx-community/gemma-4-e4b-it-OptiQ-4bit"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Hermes Agent new

How to use mlx-community/gemma-4-e4b-it-OptiQ-4bit with Hermes Agent:

Start the MLX server

# Install MLX LM:
uv tool install mlx-lm
# Start a local OpenAI-compatible server:
mlx_lm.server --model "mlx-community/gemma-4-e4b-it-OptiQ-4bit"

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default mlx-community/gemma-4-e4b-it-OptiQ-4bit

Run Hermes

hermes

OpenClaw new

How to use mlx-community/gemma-4-e4b-it-OptiQ-4bit with OpenClaw:

Start the MLX server

# Install MLX LM:
uv tool install mlx-lm
# Start a local OpenAI-compatible server:
mlx_lm.server --model "mlx-community/gemma-4-e4b-it-OptiQ-4bit"

Configure OpenClaw

# Install OpenClaw:
npm install -g openclaw@latest
# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "mlx-community/gemma-4-e4b-it-OptiQ-4bit" \
  --custom-provider-id mlx-lm \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

Run OpenClaw

openclaw agent --local --agent main --message "Hello from Hugging Face"

MLX LM

How to use mlx-community/gemma-4-e4b-it-OptiQ-4bit with MLX LM:

Generate or start a chat session

# Install MLX LM
uv tool install mlx-lm
# Interactive chat REPL
mlx_lm.chat --model "mlx-community/gemma-4-e4b-it-OptiQ-4bit"

Run an OpenAI-compatible server

# Install MLX LM
uv tool install mlx-lm
# Start the server
mlx_lm.server --model "mlx-community/gemma-4-e4b-it-OptiQ-4bit"
# Calling the OpenAI-compatible server with curl
curl -X POST "http://localhost:8000/v1/chat/completions" \
   -H "Content-Type: application/json" \
   --data '{
     "model": "mlx-community/gemma-4-e4b-it-OptiQ-4bit",
     "messages": [
       {"role": "user", "content": "Hello"}
     ]
   }'

Missing parameters

by jhmonroe - opened May 27

Discussion

jhmonroe

May 27

Trying to run this model in LM Studio yields the following error message regarding missing parameters:

🥲 Failed to load the model

Failed to load model.

Error when loading model: ValueError: Missing 54 parameters: 
language_model.model.layers.24.self_attn.k_norm.weight,
language_model.model.layers.24.self_attn.k_proj.weight,
language_model.model.layers.24.self_attn.v_proj.weight,
language_model.model.layers.25.self_attn.k_norm.weight,
language_model.model.layers.25.self_attn.k_proj.weight,
language_model.model.layers.25.self_attn.v_proj.weight,
language_model.model.layers.26.self_attn.k_norm.weight,
language_model.model.layers.26.self_attn.k_proj.weight,
language_model.model.layers.26.self_attn.v_proj.weight,
language_model.model.layers.27.self_attn.k_norm.weight,
language_model.model.layers.27.self_attn.k_proj.weight,
language_model.model.layers.27.self_attn.v_proj.weight,
language_model.model.layers.28.self_attn.k_norm.weight,
language_model.model.layers.28.self_attn.k_proj.weight,
language_model.model.layers.28.self_attn.v_proj.weight,
language_model.model.layers.29.self_attn.k_norm.weight,
language_model.model.layers.29.self_attn.k_proj.weight,
language_model.model.layers.29.self_attn.v_proj.weight,
language_model.model.layers.30.self_attn.k_norm.weight,
language_model.model.layers.30.self_attn.k_proj.weight,
language_model.model.layers.30.self_attn.v_proj.weight,
language_model.model.layers.31.self_attn.k_norm.weight,
language_model.model.layers.31.self_attn.k_proj.weight,
language_model.model.layers.31.self_attn.v_proj.weight,
language_model.model.layers.32.self_attn.k_norm.weight,
language_model.model.layers.32.self_attn.k_proj.weight,
language_model.model.layers.32.self_attn.v_proj.weight,
language_model.model.layers.33.self_attn.k_norm.weight,
language_model.model.layers.33.self_attn.k_proj.weight,
language_model.model.layers.33.self_attn.v_proj.weight,
language_model.model.layers.34.self_attn.k_norm.weight,
language_model.model.layers.34.self_attn.k_proj.weight,
language_model.model.layers.34.self_attn.v_proj.weight,
language_model.model.layers.35.self_attn.k_norm.weight,
language_model.model.layers.35.self_attn.k_proj.weight,
language_model.model.layers.35.self_attn.v_proj.weight,
language_model.model.layers.36.self_attn.k_norm.weight,
language_model.model.layers.36.self_attn.k_proj.weight,
language_model.model.layers.36.self_attn.v_proj.weight,
language_model.model.layers.37.self_attn.k_norm.weight,
language_model.model.layers.37.self_attn.k_proj.weight,
language_model.model.layers.37.self_attn.v_proj.weight,
language_model.model.layers.38.self_attn.k_norm.weight,
language_model.model.layers.38.self_attn.k_proj.weight,
language_model.model.layers.38.self_attn.v_proj.weight,
language_model.model.layers.39.self_attn.k_norm.weight,
language_model.model.layers.39.self_attn.k_proj.weight,
language_model.model.layers.39.self_attn.v_proj.weight,
language_model.model.layers.40.self_attn.k_norm.weight,
language_model.model.layers.40.self_attn.k_proj.weight,
language_model.model.layers.40.self_attn.v_proj.weight,
language_model.model.layers.41.self_attn.k_norm.weight,
language_model.model.layers.41.self_attn.k_proj.weight,
language_model.model.layers.41.self_attn.v_proj.weight.

codelion

MLX Community org May 27

The quant loads and runs fine via mlx-lm and OptIQ Lab, those missing weights (k_norm/k_proj/v_proj for layers 24-41) are intentional in Gemma-4's architecture: those layers reuse KV from earlier layers (interleaved local/global attention), so the projections don't exist in the upstream model either. LM Studio's loader doesn't yet handle the Gemma-4 shared-KV layout and expects every layer to have its own k/v weights, same error should appear on mlx-community/gemma-4-e4b-it-4bit and Google's bf16 release.

see - https://github.com/lmstudio-ai/lmstudio-bug-tracker/issues/1803 and https://github.com/lmstudio-ai/lmstudio-bug-tracker/issues/1741

For now run it via mlx-optiq instead:

  pip install -U mlx-optiq                                                                                                                                 
  optiq serve --model mlx-community/gemma-4-e4b-it-OptiQ-4bit \
              --drafter mlx-community/gemma-4-e4b-it-assistant-bf16

Demo GIF attached.

jhmonroe

May 27

•

edited May 27

Thank you!
All makes sense. Every time some new compression method comes out, it takes LM Studio a few days or weeks to catch up. Same thing happened with the last Gemma advances.
Can also confirm the errors DO NOT exist on the Optiq 26B and 31B versions. Those run in LM Studio just fine

jhmonroe

May 28

One other question: WHy are the optiq models stripped of their vision capabilities?

codelion

MLX Community org May 28

Answered it here https://huggingface.co/mlx-community/Qwen3.6-27B-OptiQ-4bit/discussions/1 but the main reason is that optiq is using mlx-lm for the actual quantization and it doesn't support the vision layers. At the moment the quants are meant for text only infernece.

Upload images, audio, and videos by dragging in the text input, pasting, or clicking here.

Tap or paste here to upload images

· Sign up or log in to comment