---
id: compel
version: "2.4.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# compel — A prompting enhancement library for transformers-type text embedding systems.

License: permissive · Maintenance: active · Downloads: 131.3K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 131.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

prompt weighting for diffusion models, text embedding control stable diffusion, prompt syntax enhancement transformers, adjust prompt influence diffusers, text prompt blending embeddings, stable diffusion prompt emphasis, weighted text conditioning, prompt-engineering, diffusion-models, text-embedding

[View on SkillFed](https://skillfed.io/packages/compel) · [View on PyPI](https://pypi.org/project/compel/)