compel

What it is and what it does

Compel is a prompt weighting library for diffusion models that lets you control how much influence different parts of a text prompt have on the final image generation. Instead of treating a prompt as a flat string, you can use syntax like `word++` to upweight a concept or `word--` to downweight it, and these weights are applied to the embedding tensor before being passed to the diffusion pipeline. It works with Hugging Face's diffusers library and supports Stable Diffusion, SDXL, and Flux models, as well as negative prompts, style prompts, and batched generation.

The library handles the tokenization and embedding transformation internally, so you just pass your weighted prompt string and get back conditioning tensors ready for the pipeline. It also supports textual inversion embeddings and provides tokenization info for debugging. The main dependencies are torch, transformers, and diffusers—all standard for generative AI work—and it has no compiled dependencies, making installation straightforward.

Use it for:

• Emphasize specific objects or attributes in Stable Diffusion prompts by using ++ or -- syntax to control their visual weight in the generated image
• Generate batches of images with different prompt weights applied consistently across multiple prompts and negative prompts
• Combine style prompts with content prompts in SDXL or Flux, with independent weighting for each component
• Integrate textual inversion embeddings into weighted prompts for fine-grained control over custom concepts
• Debug tokenization and embedding behavior by accessing tokenization_info from the conditioning output

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Compel lets you re-weight different parts of text prompts to control how much influence each part has on the embedding tensor produced by diffusion models, using an intuitive syntax like `word++` or `word--`.

Yes. Compel is actively maintained, has no security vulnerabilities, uses a permissive license, and requires only standard dependencies. It solves a real problem—fine-grained prompt control—for anyone using diffusers-based image generation. Install it if you need to adjust the relative importance of different parts of your prompts; skip it if you're happy with flat prompt strings.

Install

compel on PyPI

pip install compel

uv add compel

poetry add compel

Installing compel

Before you install

Low install friction: pure Python wheel with no compiled dependencies. Active maintenance as of 2026-05-30 with 606 repository stars. Requires Python >=3.10 and transformers >=5,<6, both standard in modern environments.

License in practice

Permissive license (MIT) means you can use, modify, and distribute Compel with minimal restrictions in commercial or open-source projects.

Quickstart

pip install compel

from diffusers import StableDiffusionPipeline
from compel import CompelForSD

pipeline = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
compel = CompelForSD(pipeline)
prompt = "a cat playing with a ball++ in the forest"
conditioning = compel(prompt)
images = pipeline(prompt_embeds=conditioning.embeds, num_inference_steps=20).images

Requires Python >=3.10 and transformers >=5,<6. Needs a compatible diffusers-based pipeline (StableDiffusionPipeline, SDXL, or Flux) already instantiated.

Verify before relying

• Whether memory/VRAM leak workarounds (torch.no_grad blocks, explicit tensor dereferencing) are still necessary in current versions
• Performance overhead of Compel's prompt parsing and reweighting relative to raw embeddings

Package facts

Evidence: compel-2.4.0-py3-none-any.whl

Tags

More Artificial Intelligence packages

Further reading