Generate the BAML Client

Once you’ve defined a function in BAML, you need to generate code in your language of choice to call that function: we call this generating the BAML client.

If you use VSCode, the BAML extension will re-generate the client every time you save a BAML file. Otherwise, you can generate the client manually:

$
pipx run baml-cli generate --from path/to/baml_src
>
>
# If using your local installation, venv or conda:
>
pip install baml-py
>
baml-cli generate --from path/to/baml_src
>
>
# If using poetry:
>
poetry add baml-py
>
poetry run baml-cli generate --from path/to/baml_src
>
>
# If using pipenv:
>
pipenv install baml-py
>
pipenv run baml-cli generate --from path/to/baml_src

Best Practices

Define a generator clause

Each generator that you define in your BAML project will tell baml-cli generate to generate code for a specific target language. You can define multiple generator clauses in your BAML project, and baml-cli generate will generate code for each of them.

1
generator target {
2
    // Valid values: "python/pydantic", "typescript", "ruby/sorbet"
3
    output_type "python/pydantic"
4
    
5
    // Where the generated code will be saved (relative to baml_src/)
6
    output_dir "../"
7
    
8
    // What interface you prefer to use for the generated code (sync/async)
9
    // Both are generated regardless of the choice, just modifies what is exported
10
    // at the top level
11
    default_client_mode "sync"
12
    
13
    // Version of runtime to generate code for (should match installed baml-py version)
14
    version "0.50.0"
15
}

Generate the BAML client on-demand

Although you can check in the generated BAML client, we recommend that you instead add it to your .gitignore and generate it on-demand when you build/release your code:

• this will make your PRs more readable;
• this will save you from handling merge conflicts in generated code; and
• this will ensure a single source-of-truth for your BAML code (and prevent your client from falling out of sync with your BAML code).

To add the generated client to your .gitignore, you can run:

$
echo "baml_client" >> .gitignore

and then you just need to run baml-cli generate in your CI/CD build/release workflows. Here’s what that might look like in a GitHub Actions workflow file:

1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    steps:
5
      - uses: actions/checkout@v4
6
7
      # Install your Python/Node/Ruby (beta) dependencies here
8
9
      - name: Generate BAML client
10
        run: baml-cli generate --from baml_src

Troubleshooting version conflicts

baml_client can be generated in 2 ways:

1. VSCode extension
2. the installed baml dependency (e.g., baml-py)

Since the extension auto-updates, it’s possible that it stops generating the client due to a version mismatch with the generator version. You might see an error like:

$
BAML: Code Generation disabled due to version mismatch... See the fix.

To fix any version mismatch issues, update all these things to the same version:

1. VSCode extension
2. the installed baml dependency (e.g., baml-py)

• python: pip install --upgrade baml-py
• typescript: npm install @boundaryml/baml@latest

3. the version in your generator clause

Only the minor and major versions are checked for compatibility (0.0.x).

You can also tweak the generator settings below for a better experience.

VSCode generator settings

baml.cliPath

stringDefaults to null

If set, will make the extension use the baml-cli you have installed on your system to generate the client. This prevents mismatches between the generated code and the installed BAML package.

If you use unix, you can run where baml-cli in your project to figure out what the path is.

If you have multiple BAML projects, ensure that this path is set to baml package installed for that project.

baml-cli generate arguments