outlines

library1.3.3pypypi✓ verified 25d ago

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.

llm-agents ai-ml serialization

pip install outlines

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · OUTLINES

outlines

llm-agentspythonv1.3.3

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.3 · 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

3/4 runs

py 3.11

✕ build_error

3/4 runs

py 3.12

✕ build_error

3/4 runs

py 3.13

✕ build_error

3/4 runs

py 3.9

✕ build_error

2/4 runs

Code

Verified usage

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

Generator

✓ from outlines import Generator

✗ import outlines; model = outlines.from_transformers(hf_model, hf_tokenizer)

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

Debug

Known issues

breakingPython 3.9 not supported. outlines requires Python >=3.10.

fix

Upgrade to Python 3.10+.

affects: all

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

affects: < 0.1.0

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

affects: < 0.1.0

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

affects: all

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

affects: >= 1.0.0

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

affects: all

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

affects: all

gotchaOptional[...] = 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.

affects: all

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

affects: all

Upgrade

Version history

1.3.3latest on PyPI · released Aug 6, 2026

Audit

Dependencies

outlines-corerequiredRust-based FSM engine. Installed automatically as a dependency of outlines. Do not install or pin separately — outlines manages the version.

transformersoptionalRequired for Transformers/TransformersVision backends. Not bundled in base install.

vllmoptionalRequired for vLLM backend.

llama-cpp-pythonoptionalRequired for llama.cpp backend.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dottxt-ai/outlines ↗

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

homepagehttps://dottxt.co ↗

docshttps://dottxt-ai.github.io/outlines/ ↗