compel

library2.4.0pypypi✓ verified 86d ago

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.

ai-ml llm-agents

pip install compel

github ↗package ↗

INSTALL

IMPORT

SIG · COMPEL

compel

ai-mlpythonv2.4.0

Install

79.9s avg

Import

18873ms

Disk

5325MB

Pass rate

1/ 10

Env Coverage1 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✕ timeout

py 3.11

✕ build_error

✕ timeout

py 3.12

✕ build_error

✕ timeout

py 3.13

✕ build_error

✓ 79.88s

py 3.9

✕ build_error

✕ timeout

5325MB installed

● package 5325MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Compel

✓ from compel import Compel

✗ from compel.compel import Compel

The primary class for general prompt manipulation. Older versions sometimes used the direct module path.

CompelForSD

✓ from compel import CompelForSD

Specialized wrapper for Stable Diffusion v1.x/v2.x pipelines.

CompelForSDXL

✓ from compel import CompelForSDXL

Specialized wrapper for Stable Diffusion XL pipelines, handling multiple tokenizers and pooled embeddings.

ReturnedEmbeddingsType

✓ from compel import ReturnedEmbeddingsType

Enum used for configuring which text encoder layer embeddings are returned, especially for 'clip skip' or SDXL.

DownweightMode

✓ from compel import DownweightMode

Enum used to configure the downweighting algorithm, e.g., MASK (default) or REMOVE (legacy).

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.

import torch from diffusers import DiffusionPipeline from compel import CompelForSDXL # Ensure you have a Hugging Face token if the model is private or gated # os.environ['HF_TOKEN'] = os.environ.get('HF_TOKEN', '') # Load an SDXL pipeline pipeline = DiffusionPipeline.from_pretrained( "stabilityai/stable-diffusion-xl-base-1.0", variant="fp16", use_safetensors=True, torch_dtype=torch.float16 ).to("cuda") # Or 'cpu' if no GPU # Initialize CompelForSDXL with the pipeline compel = CompelForSDXL(pipeline) # Define prompts with weighting syntax positive_prompt = "A cat playing with a ball++ in the forest, (high quality, photorealistic)1.2" negative_prompt = "deformed, ugly, blurry, out of focus, worst quality, low quality-" # Generate conditioning tensors conditioning = compel(positive_prompt) negative_conditioning = compel(negative_prompt) # For SDXL, prompt_embeds and pooled_prompt_embeds are used image = pipeline( prompt_embeds=conditioning.embeds, pooled_prompt_embeds=conditioning.pooled_embeds, negative_prompt_embeds=negative_conditioning.embeds, negative_pooled_prompt_embeds=negative_conditioning.pooled_embeds, num_inference_steps=30, width=1024, height=1024 ).images[0] # Save the generated image # image.save("compel_example_image.png") print("Image generated successfully.")

Debug

Known issues

breakingWith 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`).

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.

affects: >=2.0.0

breakingIn 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.

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.

affects: >=1.0.0

gotchaWhen 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.

fix

Initialize `Compel` or `CompelForSDXL` with `device='cuda'` (or your desired GPU device) explicitly: `compel = CompelForSDXL(pipeline, device='cuda')`.

affects: 2.0.2 - 2.3.0

gotchaFor 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.

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.

affects: All versions

gotchaTo avoid VRAM leaks and manage memory efficiently, especially in iterative generation loops, ensure `compel` operations are performed within a `with torch.no_grad():` block.

fix

Wrap your `compel` calls and subsequent pipeline inference within `with torch.no_grad():`.

affects: All versions

Errors

Common errors & fixes

RuntimeError: Sizes of tensors must match except in dimension 1. Expected size 77 but got size 154 for tensor number X in the list.

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.

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()`.

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.

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.

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`).

Upgrade

Version history

2.4.0latest on PyPI · released May 30, 2026

Audit

Dependencies

diffusersrequiredCore integration for diffusion pipelines (e.g., Stable Diffusion, SDXL).

torchrequiredUnderlying deep learning framework for tensor operations.

transformersrequiredText encoder and tokenizer components for embedding systems.

notebookoptionalLikely for demo notebooks and interactive usage.

pyparsingrequiredUsed for parsing the specialized prompt syntax.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/damian0815/compel ↗

packagehttps://pypi.org/project/compel/ ↗