Outlines

1.2.11 verified Tue May 12 auth: no python install: stale quickstart: stale

Structured generation library by .txt (dottxt-ai). Guarantees schema-valid outputs at generation time via FSM-based logits masking — no post-processing or retries. Supports regex, JSON schema (Pydantic or raw), CFG, and multiple-choice constraints. Backends: Transformers, vLLM, llama.cpp, MLX, Ollama, OpenAI, Mistral, Gemini. Core FSM engine split into separate outlines-core package (Rust). Two coexisting APIs: legacy outlines.models + outlines.generate.* style, and new 1.x outlines.from_* + model(prompt, Schema) style.

pip install outlines

Common errors

error ModuleNotFoundError: No module named 'outlines.fsm' ↓

cause This error typically occurs when the `outlines` library is not correctly installed, or if there have been breaking changes in the module structure (e.g., `outlines.fsm` moving into `outlines-core` in newer versions) and an outdated `outlines` package is installed, or when running code from an uninstalled source directory without proper setup.

fix

Ensure outlines is properly installed with pip install outlines. If running from source, use pip install -e . from the project root. For specific versions, check the outlines changelog for module path changes and upgrade your outlines installation if necessary to a compatible version.

error AttributeError: 'CFGGuide' object has no attribute 'regex_fsm' ↓

cause This `AttributeError` indicates an internal issue within the `outlines` library's Context-Free Grammar (CFG) FSM implementation, where a required attribute (`regex_fsm`) is not initialized before being accessed, often seen in specific `outlines` versions (e.g., 0.26) when `next_state()` is called before `allowed_token_ids()`.

fix

Upgrade to a newer version of outlines as this was a known bug that has likely been patched. If upgrading is not immediately possible, check the library's GitHub issues for hotfixes or workarounds specific to your outlines version.

error ImportError: cannot import name 'build_regex_from_object' from 'outlines.fsm.json_schema' ↓

cause This `ImportError` arises from breaking changes in the `outlines` library's internal API, specifically the `outlines.fsm` module, where `build_regex_from_object` or similar functions might have been moved, renamed, or removed in newer versions (e.g., after `outlines` 0.1.0).

fix

Update your outlines library to the latest version via pip install --upgrade outlines. If you are working with a project that requires an older outlines version, consult the outlines documentation or GitHub history for the correct import paths for that specific version.

error AttributeError: 'TransformerTokenizer' object has no attribute 'all_special_tokens' ↓

cause This error occurs when an `outlines.models.TransformerTokenizer` instance is initialized incorrectly, specifically when the underlying HuggingFace `AutoTokenizer` object is not passed to the `outlines` wrapper in the expected way, leading to missing attributes that `outlines` expects for its internal operations.

fix

Ensure you are initializing the outlines transformer model correctly by passing the transformers.AutoTokenizer.from_pretrained() result directly to outlines.models.transformers() or outlines.models.TransformerTokenizer(), rather than an already wrapped tokenizer. For example: model = outlines.models.transformers('microsoft/Phi-3-mini-4k-instruct') or outlines_tokenizer = outlines.models.TransformerTokenizer(transformers.AutoTokenizer.from_pretrained(model_uri)).

error Pydantic ValidationError: Invalid control character at ↓

cause This `Pydantic ValidationError` typically occurs when `outlines` is used for structured JSON generation, but the underlying language model emits output that contains invalid characters (e.g., unescaped control characters) within a JSON string, which then causes Pydantic to fail validation against the defined schema.

fix

This often points to the model struggling to generate valid JSON. Try simplifying your prompt or JSON schema, ensuring the model is capable of generating JSON, or experimenting with different models. Upgrading outlines might also help if there are improvements in the FSM logic for handling edge cases.

Warnings

breaking Python 3.9 not supported. outlines requires Python >=3.10. ↓

fix Upgrade to Python 3.10+.

breaking outlines.integrations module removed in 0.1.0. Any code importing from outlines.integrations raises ImportError. ↓

fix Use outlines.processors directly (RegexLogitsProcessor, JSONLogitsProcessor, CFGLogitsProcessor) for custom logits processor integration.

breaking outlines.fsm.json_schema.build_regex_from_object removed. Old low-level FSM imports from outlines.fsm are gone — this module was split into outlines-core. ↓

fix Use high-level outlines.generate.json() or outlines.generate.regex() instead of constructing FSMs directly.

breaking pip install outlines installs no inference backend. Importing any model backend without its extra raises ImportError at runtime. ↓

fix Install the required extra: pip install 'outlines[transformers]', 'outlines[vllm]', 'outlines[llamacpp]', etc.

gotcha Two coexisting APIs in 1.x. Old style: outlines.models.transformers('name') + outlines.generate.json(model, Schema)(prompt). New style: outlines.from_transformers(hf_model, tokenizer) + model(prompt, Schema). Both work but mix-and-match fails — old model objects are not compatible with the new model(prompt, Schema) call signature. ↓

fix Pick one API style per codebase. New style is recommended. Old style is still valid for outlines.generate.* generators.

gotcha OpenAI and other API backends do NOT support regex or CFG constraints. generate.regex / generate.cfg silently falls back to prompt-only steering or raises NotImplementedError. ↓

fix Use local backends (Transformers, vLLM, llama.cpp) for hard regex/CFG constraints. API backends only support JSON schema via the provider's native structured output API.

gotcha FSM index compilation is expensive for complex JSON schemas. generate.json(model, Schema) compiles once and must be reused — calling it fresh per request tanks throughput. ↓

fix Create generator/model+schema pair once at startup and call it repeatedly. Do not re-instantiate per request.

gotcha Optional[...] = None fields in Pydantic schemas can cause FSM compilation to hang for minutes or never complete on complex schemas. ↓

fix Avoid Optional fields with complex nested types in large schemas. Use Union[SpecificType, None] with simpler types, or restructure the schema to eliminate unbounded optional nesting.

breaking Installing `outlines` (or its dependency `outlines_core`) in minimal Linux environments (like Alpine Linux) may fail due to missing C/C++ runtime libraries required by the Rust toolchain used for compilation. The error typically manifests as `Error loading shared library libgcc_s.so.1: No such file or directory` or similar relocation errors when `cargo` attempts to run during package metadata generation. ↓

fix Ensure a C/C++ build environment is available. For Alpine Linux, install `gcc` and `libc-dev` (e.g., `apk add build-base gcc libc-dev`). For other minimal environments, consult their documentation for installing development tools and C/C++ runtime libraries.

Install

pip install 'outlines[transformers]'

pip install 'outlines[vllm]'

pip install 'outlines[llamacpp]'

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) llamacpp - - - -

3.10 alpine (musl) transformers - - - -

3.10 alpine (musl) vllm - - - -

3.10 alpine (musl) outlines - - - -

3.10 slim (glibc) llamacpp - - - -

3.10 slim (glibc) transformers - - - -

3.10 slim (glibc) vllm - - - -

3.10 slim (glibc) outlines - - - -

3.11 alpine (musl) llamacpp - - - -

3.11 alpine (musl) transformers - - - -

3.11 alpine (musl) vllm - - - -

3.11 alpine (musl) outlines - - - -

3.11 slim (glibc) llamacpp - - - -

3.11 slim (glibc) transformers - - - -

3.11 slim (glibc) vllm - - - -

3.11 slim (glibc) outlines - - - -

3.12 alpine (musl) llamacpp - - - -

3.12 alpine (musl) transformers - - - -

3.12 alpine (musl) vllm - - - -

3.12 alpine (musl) outlines - - - -

3.12 slim (glibc) llamacpp - - - -

3.12 slim (glibc) transformers - - - -

3.12 slim (glibc) vllm - - - -

3.12 slim (glibc) outlines - - - -

3.13 alpine (musl) llamacpp - - - -

3.13 alpine (musl) transformers - - - -

3.13 alpine (musl) vllm - - - -

3.13 alpine (musl) outlines - - - -

3.13 slim (glibc) llamacpp - - - -

3.13 slim (glibc) transformers - - - -

3.13 slim (glibc) vllm - - - -

3.13 slim (glibc) outlines - - - -

3.9 alpine (musl) llamacpp - - - -

3.9 alpine (musl) transformers - - - -

3.9 alpine (musl) vllm - - - -

3.9 alpine (musl) outlines - - - -

3.9 slim (glibc) llamacpp - - - -

3.9 slim (glibc) transformers - - - -

3.9 slim (glibc) vllm - - - -

3.9 slim (glibc) outlines - - - -

Imports

from_transformers
wrong
```
import outlines; model = outlines.models.transformers('gpt2')
```
correct
```
import outlines; model = outlines.from_transformers(hf_model, hf_tokenizer)
```
1.x preferred API takes pre-initialized HF model + tokenizer objects. The old outlines.models.transformers('model-name') string-based loader still works in 1.x but is the legacy pattern — tutorials and LLM-generated code overwhelmingly use the old style.
from_openai
wrong
```
import outlines; model = outlines.models.openai('gpt-4o', api_key=...)
```
correct
```
import outlines; model = outlines.from_openai(openai_client, 'gpt-4o')
```
1.x API takes an initialized OpenAI client object. Note: OpenAI backend does NOT support regex/CFG constraints — only JSON schema via OpenAI's structured outputs API.

Quickstart stale last tested: 2026-05-12

1.x API: pass output type directly to model call. For local models, swap outlines.from_openai for outlines.from_transformers.

import outlines
from pydantic import BaseModel
from typing import Literal
import openai

class Customer(BaseModel):
    name: str
    urgency: Literal['high', 'medium', 'low']
    issue: str

client = openai.OpenAI()
model = outlines.from_openai(client, 'gpt-4o')

customer = model(
    'Alice needs help with login issues ASAP',
    Customer
)
print(customer)  # Always returns valid Customer object