{"id":8028,"library":"compel","title":"Compel","description":"Compel is an active Python library, currently at version 2.3.1, designed to enhance prompting for transformers-type text embedding systems. It provides a flexible and intuitive syntax for sophisticated prompt weighting, blending, and concatenation, commonly used with Hugging Face `diffusers` pipelines. The library aims to give users granular control over how text encoders interpret complex prompt strings, and it maintains a regular release cadence with ongoing development.","status":"active","version":"2.3.1","language":"en","source_language":"en","source_url":"https://github.com/damian0815/compel","tags":["prompting","transformers","text-embedding","stable-diffusion","diffusers","AI","image-generation"],"install":[{"cmd":"pip install compel","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core integration for diffusion pipelines (e.g., Stable Diffusion, SDXL).","package":"diffusers","optional":false},{"reason":"Underlying deep learning framework for tensor operations.","package":"torch","optional":false},{"reason":"Text encoder and tokenizer components for embedding systems.","package":"transformers","optional":false},{"reason":"Likely for demo notebooks and interactive usage.","package":"notebook","optional":true},{"reason":"Used for parsing the specialized prompt syntax.","package":"pyparsing","optional":false}],"imports":[{"note":"The primary class for general prompt manipulation. Older versions sometimes used the direct module path.","wrong":"from compel.compel import Compel","symbol":"Compel","correct":"from compel import Compel"},{"note":"Specialized wrapper for Stable Diffusion v1.x/v2.x pipelines.","symbol":"CompelForSD","correct":"from compel import CompelForSD"},{"note":"Specialized wrapper for Stable Diffusion XL pipelines, handling multiple tokenizers and pooled embeddings.","symbol":"CompelForSDXL","correct":"from compel import CompelForSDXL"},{"note":"Enum used for configuring which text encoder layer embeddings are returned, especially for 'clip skip' or SDXL.","symbol":"ReturnedEmbeddingsType","correct":"from compel import ReturnedEmbeddingsType"},{"note":"Enum used to configure the downweighting algorithm, e.g., MASK (default) or REMOVE (legacy).","symbol":"DownweightMode","correct":"from compel import DownweightMode"}],"quickstart":{"code":"import torch\nfrom diffusers import DiffusionPipeline\nfrom compel import CompelForSDXL\n\n# Ensure you have a Hugging Face token if the model is private or gated\n# os.environ['HF_TOKEN'] = os.environ.get('HF_TOKEN', '')\n\n# Load an SDXL pipeline\npipeline = DiffusionPipeline.from_pretrained(\n    \"stabilityai/stable-diffusion-xl-base-1.0\",\n    variant=\"fp16\",\n    use_safetensors=True,\n    torch_dtype=torch.float16\n).to(\"cuda\") # Or 'cpu' if no GPU\n\n# Initialize CompelForSDXL with the pipeline\ncompel = CompelForSDXL(pipeline)\n\n# Define prompts with weighting syntax\npositive_prompt = \"A cat playing with a ball++ in the forest, (high quality, photorealistic)1.2\"\nnegative_prompt = \"deformed, ugly, blurry, out of focus, worst quality, low quality-\"\n\n# Generate conditioning tensors\nconditioning = compel(positive_prompt)\nnegative_conditioning = compel(negative_prompt)\n\n# For SDXL, prompt_embeds and pooled_prompt_embeds are used\nimage = pipeline(\n    prompt_embeds=conditioning.embeds,\n    pooled_prompt_embeds=conditioning.pooled_embeds,\n    negative_prompt_embeds=negative_conditioning.embeds,\n    negative_pooled_prompt_embeds=negative_conditioning.pooled_embeds,\n    num_inference_steps=30,\n    width=1024,\n    height=1024\n).images[0]\n\n# Save the generated image\n# image.save(\"compel_example_image.png\")\nprint(\"Image generated successfully.\")","lang":"python","description":"This quickstart demonstrates how to use `CompelForSDXL` with a Hugging Face `diffusers` pipeline to apply weighting to both positive and negative prompts. It showcases the `++` and explicit number weighting syntax, and how to retrieve and pass the generated conditioning tensors (embeds and pooled_embeds) to the SDXL pipeline for image generation. Ensure you have `diffusers` and `torch` installed and a suitable Hugging Face model loaded."},"warnings":[{"fix":"Update `Compel` initialization to use `returned_embeddings_type=ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NON_NORMALIZED` for SDXL, or `ReturnedEmbeddingsType.LAST_HIDDEN_STATES_NORMALIZED` for SD<=2.1.","message":"With Compel v2.0.0, the API for controlling returned embeddings changed for SDXL support. The boolean argument `use_penultimate_clip_layer` was replaced by the `returned_embeddings_type` enum (e.g., `ReturnedEmbeddingsType.PENULTIMATE_HIDDEN_STATES_NORMALIZED`).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If you rely on the legacy downweighting behavior (token removal), initialize `Compel` with `downweight_mode=DownweightMode.REMOVE`. Otherwise, no change is needed as masking is the default and recommended.","message":"In v1.0.0, the downweighting algorithm was changed to mask tokens (default) instead of literally removing them. This new behavior preserves positional embeddings, but the old behavior can be re-enabled if necessary.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Initialize `Compel` or `CompelForSDXL` with `device='cuda'` (or your desired GPU device) explicitly: `compel = CompelForSDXL(pipeline, device='cuda')`.","message":"When using `pipeline.enable_sequential_cpu_offloading()` with SDXL models, `compel` may require explicit device assignment to prevent issues. This was addressed in v2.0.2.","severity":"gotcha","affected_versions":"2.0.2 - 2.3.0"},{"fix":"Always pass both positive and negative conditioning tensors through `compel.pad_conditioning_tensors_to_same_length([positive_embeds, negative_embeds])` before passing them to the diffusion pipeline.","message":"For long prompts (when `truncate_long_prompts=False`) or prompts using the `.and()` operator, conditioning tensors for positive and negative prompts may have different lengths, leading to errors in the diffusion pipeline.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap your `compel` calls and subsequent pipeline inference within `with torch.no_grad():`.","message":"To avoid VRAM leaks and manage memory efficiently, especially in iterative generation loops, ensure `compel` operations are performed within a `with torch.no_grad():` block.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For SDXL, ensure `CompelForSDXL` is correctly initialized with both tokenizers and text encoders (`compel = CompelForSDXL(pipeline)`). If the issue persists with special characters like '!', a workaround is to initialize `Compel` with a duplicated tokenizer for both: `compel = Compel(tokenizer=[pipeline.tokenizer, pipeline.tokenizer], text_encoder=[pipeline.text_encoder, pipeline.text_encoder_2], ...)` as a temporary fix, along with `truncate_long_prompts=False` and `pad_conditioning_tensors_to_same_length()`.","cause":"This error often occurs with SDXL when its two tokenizers (`tokenizer` and `tokenizer_2`) produce conditioning tensors of different sequence lengths, typically due to differing padding tokens or specific prompt characters (like `!`) causing disparate tokenization lengths across the two text encoders.","error":"RuntimeError: Sizes of tensors must match except in dimension 1. Expected size 77 but got size 154 for tensor number X in the list."},{"fix":"If you intend to use long prompts, ensure `truncate_long_prompts=False` is set in `Compel` initialization and always use `compel.pad_conditioning_tensors_to_same_length()` for all conditioning tensors. If truncation is desired, ensure `truncate_long_prompts=True` (which is the default behavior in `Compel`).","cause":"This warning (or sometimes an error if not handled) indicates that an input prompt exceeds the maximum token length (typically 77 tokens for many Stable Diffusion models). It appears when `truncate_long_prompts=False` is set during `Compel` initialization, allowing longer prompts that are then chunked.","error":"Token indices sequence length is longer than the specified maximum sequence length for this model (XXX > 77). Running this sequence through the model will result in indexing errors."}]}