Skip to main content
This guide will help you install BAML, create your first function, and call it from your application.

​
Choose Your Language

BAML works with Python, TypeScript, Ruby, Go, and any language via REST API.
1
Install the VSCode Extension
2
First, install the BAML VSCode extension for the best developer experience:
3
BAML VSCode Extension
4
Features:
5
  • Syntax highlighting for .baml files
  • Built-in testing playground
  • Live prompt previews
  • Auto-generates baml_client on save
  • Jump to definition support
    • 6
    The extension works with VSCode, Cursor, and other VSCode-compatible editors. JetBrains and Neovim support coming soon.
    7
    Install BAML Package
    8
    Python (pip)
    pip install baml-py
    Python (poetry)
    poetry add baml-py
    Python (uv)
    uv add baml-py
    TypeScript (npm)
    npm install @boundaryml/baml
    TypeScript (pnpm)
    pnpm add @boundaryml/baml
    TypeScript (yarn)
    yarn add @boundaryml/baml
    TypeScript (bun)
    bun add @boundaryml/baml
    9
    Initialize BAML in Your Project
    10
    Run the init command to create a baml_src directory with starter code:
    11
    Python (pip)
    baml-cli init
    Python (poetry)
    poetry run baml-cli init
    Python (uv)
    uv run baml-cli init
    TypeScript (npm)
    npx baml-cli init
    TypeScript (pnpm)
    pnpm exec baml-cli init
    TypeScript (yarn)
    yarn baml-cli init
    12
    This creates:
    13
  • baml_src/ - Directory for your BAML files
  • baml_src/main.baml - Example function
  • baml_src/clients.baml - LLM client configurations
  • baml_src/generators.baml - Code generation settings
    • 14
    Create Your First BAML Function
    15
    Open baml_src/main.baml and create a function to extract structured data from text:
    16
    class Receipt {
  establishment_name string
  date string @description("ISO8601 formatted date")
  total int
  currency string
  items Item[]
}

class Item {
  name string
  price float
  quantity int
}

function ExtractReceipt(receipt: image | string) -> Receipt {
  client GPT4o
  
  prompt #"
    {{ _.role("user") }}
    
    Extract info from this receipt:
    {{ receipt }}
    
    {{ ctx.output_format }}
  "#
}

test ReceiptTest {
  functions [ExtractReceipt]
  args {
    receipt #"
      Starbucks
      Date: 2024-03-15
      Total: $12.50 USD
      Items:
      - Coffee $4.50 x 2
      - Croissant $3.50 x 1
    "#
  }
}
    17
    Configure Your LLM Client
    18
    In baml_src/clients.baml, configure your API keys:
    19
    client<llm> GPT4o {
  provider openai
  options {
    model gpt-4o
    api_key env.OPENAI_API_KEY
  }
}

client<llm> Claude {
  provider anthropic
  options {
    model claude-3-haiku-20240307
    api_key env.ANTHROPIC_API_KEY
    max_tokens 1000
  }
}
    20
    Make sure to set your API keys in your environment variables or .env file.
    21
    Generate the Client Code
    22
    Generate the type-safe baml_client from your BAML files:
    23
    Python (pip)
    baml-cli generate
    Python (poetry)
    poetry run baml-cli generate
    Python (uv)
    uv run baml-cli generate
    TypeScript (npm)
    npx baml-cli generate
    TypeScript (pnpm)
    pnpm exec baml-cli generate
    TypeScript (yarn)
    yarn baml-cli generate
    24
    This creates:
    25
  • baml_client/ - Auto-generated client code
  • Type definitions (Pydantic models for Python, TypeScript interfaces)
  • Function wrappers with full type safety
    • 26
    The VSCode extension automatically runs baml-cli generate when you save a .baml file!
    27
    Test in the Playground
    28
    Open any .baml file in VSCode and click the “Open Playground” button above your function, or use the command palette (Cmd/Ctrl + Shift + P) and search for “BAML Playground”.
    29
    In the playground:
    30
  • Click the Settings button to set your API keys
  • Click the play button to run your test
  • See the full prompt, API request, and parsed response
  • Iterate on your prompt and see changes instantly
    • 31
    The playground lets you test prompts 10x faster than running your whole application.
    32
    Call BAML from Your Code
    33
    Now use the generated baml_client in your application:
    34
    Python (Sync)
    from baml_client.sync_client import b
from baml_client.types import Receipt

# Call the function
receipt = b.ExtractReceipt(
    receipt="Starbucks\nTotal: $12.50 USD"
)

# Fully typed response
print(receipt.establishment_name)
print(receipt.total)
print(receipt.items[0].name)
    Python (Async)
    from baml_client.async_client import b
from baml_client.types import Receipt

async def main():
    receipt = await b.ExtractReceipt(
        receipt="Starbucks\nTotal: $12.50 USD"
    )
    print(receipt.establishment_name)
    Python (Streaming)
    from baml_client.async_client import b

async def main():
    stream = b.stream.ExtractReceipt(
        receipt="Starbucks\nTotal: $12.50 USD"
    )
    
    async for partial in stream:
        # partial is PartialReceipt with optional fields
        print(partial.establishment_name)
    
    # Get final complete response
    final = await stream.get_final_response()
    TypeScript (Async)
    import { b } from './baml_client'
import type { Receipt } from './baml_client/types'

async function main() {
  const receipt = await b.ExtractReceipt(
    'Starbucks\nTotal: $12.50 USD'
  )
  
  console.log(receipt.establishment_name)
  console.log(receipt.total)
  console.log(receipt.items[0].name)
}
    TypeScript (Streaming)
    import { b } from './baml_client'

async function main() {
  const stream = b.stream.ExtractReceipt(
    'Starbucks\nTotal: $12.50 USD'
  )
  
  for await (const partial of stream) {
    // partial is Partial<Receipt>
    console.log(partial.establishment_name)
  }
  
  const final = await stream.getFinalResponse()
}

    ​
    What You Get

    Type Safety

    Full autocomplete and type checking in your IDE. BAML generates Pydantic models (Python) or TypeScript interfaces.

    Streaming Support

    Stream partial responses with type-safe intermediate states.

    Built-in Testing

    Test functions directly in VSCode without running your app.

    Multiple Models

    Easily switch between OpenAI, Anthropic, Gemini, and more.

    ​
    Next Steps

    Add Retries & Fallbacks

    Make your functions more reliable

    Use Images & PDFs

    Process multimodal inputs

    Build an Agent

    Create stateful AI workflows

    ​
    Common Issues

    Can’t find baml_client? Make sure you ran baml-cli generate after creating your .baml files.
    Python autocomplete not working? Add this to your VSCode settings:
    {
  "python.analysis.typeCheckingMode": "basic"
}

    ​
    Get Help

    Build docs developers (and LLMs) love

    Get started for freeTalk to us