{"id":57,"library":"outlines","title":"Outlines","description":"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.","status":"active","version":"1.2.11","language":"python","source_language":"en","source_url":"https://dottxt-ai.github.io/outlines/latest/","tags":["outlines","structured-generation","constrained-decoding","json-schema","regex","pydantic","vllm","transformers","llama-cpp","fsm"],"install":[{"cmd":"pip install outlines","lang":"bash","label":"Base (no backends)"},{"cmd":"pip install 'outlines[transformers]'","lang":"bash","label":"Transformers backend"},{"cmd":"pip install 'outlines[vllm]'","lang":"bash","label":"vLLM backend"},{"cmd":"pip install 'outlines[llamacpp]'","lang":"bash","label":"llama.cpp backend"}],"dependencies":[{"reason":"Rust-based FSM engine. Installed automatically as a dependency of outlines. Do not install or pin separately — outlines manages the version.","package":"outlines-core","optional":false},{"reason":"Required for Transformers/TransformersVision backends. Not bundled in base install.","package":"transformers","optional":true},{"reason":"Required for vLLM backend.","package":"vllm","optional":true},{"reason":"Required for llama.cpp backend.","package":"llama-cpp-python","optional":true}],"imports":[{"note":"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.","wrong":"import outlines; model = outlines.models.transformers('gpt2')","symbol":"from_transformers","correct":"import outlines; model = outlines.from_transformers(hf_model, hf_tokenizer)"},{"note":"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.","wrong":"import outlines; model = outlines.models.openai('gpt-4o', api_key=...)","symbol":"from_openai","correct":"import outlines; model = outlines.from_openai(openai_client, 'gpt-4o')"}],"quickstart":{"code":"import outlines\nfrom pydantic import BaseModel\nfrom typing import Literal\nimport openai\n\nclass Customer(BaseModel):\n    name: str\n    urgency: Literal['high', 'medium', 'low']\n    issue: str\n\nclient = openai.OpenAI()\nmodel = outlines.from_openai(client, 'gpt-4o')\n\ncustomer = model(\n    'Alice needs help with login issues ASAP',\n    Customer\n)\nprint(customer)  # Always returns valid Customer object","lang":"python","description":"1.x API: pass output type directly to model call. For local models, swap outlines.from_openai for outlines.from_transformers."},"warnings":[{"fix":"Upgrade to Python 3.10+.","message":"Python 3.9 not supported. outlines requires Python >=3.10.","severity":"breaking","affected_versions":"all"},{"fix":"Use outlines.processors directly (RegexLogitsProcessor, JSONLogitsProcessor, CFGLogitsProcessor) for custom logits processor integration.","message":"outlines.integrations module removed in 0.1.0. Any code importing from outlines.integrations raises ImportError.","severity":"breaking","affected_versions":"< 0.1.0"},{"fix":"Use high-level outlines.generate.json() or outlines.generate.regex() instead of constructing FSMs directly.","message":"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.","severity":"breaking","affected_versions":"< 0.1.0"},{"fix":"Install the required extra: pip install 'outlines[transformers]', 'outlines[vllm]', 'outlines[llamacpp]', etc.","message":"pip install outlines installs no inference backend. Importing any model backend without its extra raises ImportError at runtime.","severity":"breaking","affected_versions":"all"},{"fix":"Pick one API style per codebase. New style is recommended. Old style is still valid for outlines.generate.* generators.","message":"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.","severity":"gotcha","affected_versions":">= 1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Create generator/model+schema pair once at startup and call it repeatedly. Do not re-instantiate per request.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Optional[...] = None fields in Pydantic schemas can cause FSM compilation to hang for minutes or never complete on complex schemas.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T06:14:46.863Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'outlines.fsm'"},{"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.","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()`.","error":"AttributeError: 'CFGGuide' object has no attribute 'regex_fsm'"},{"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.","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).","error":"ImportError: cannot import name 'build_regex_from_object' from 'outlines.fsm.json_schema'"},{"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))`.","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.","error":"AttributeError: 'TransformerTokenizer' object has no attribute 'all_special_tokens'"},{"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.","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.","error":"Pydantic ValidationError: Invalid control character at"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"llamacpp","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"vllm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}