ABI Versioning

Understanding parser compatibility and ABI version requirements

Introduction

Parsers generated with Tree-sitter have an associated ABI (Application Binary Interface) version, which establishes hard compatibility boundaries between the generated parser and the Tree-sitter library.

A given version of the Tree-sitter library is only able to load parsers generated with supported ABI versions.

Current ABI Version

The latest ABI version is defined in the Tree-sitter API:

#define TREE_SITTER_LANGUAGE_VERSION 15
#define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 13

Latest ABI

Version 15 - The latest ABI version supported by the current library

Minimum ABI

Version 13 - The earliest ABI version that can still be loaded

C

#include <tree_sitter/api.h>

const TSLanguage *language = tree_sitter_json();
uint32_t abi_version = ts_language_abi_version(language);

printf("Parser ABI version: %u\n", abi_version);
printf("Library supports: %u-%u\n",
       TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION,
       TREE_SITTER_LANGUAGE_VERSION);

if (abi_version < TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION ||
    abi_version > TREE_SITTER_LANGUAGE_VERSION) {
    fprintf(stderr, "Incompatible ABI version!\n");
}

Compatibility Matrix

The following table shows which ABI versions are supported by which Tree-sitter library versions:

Tree-sitter Version	Min Parser ABI	Max Parser ABI
0.14	9	9
≥ 0.15.0, ≤ 0.15.7	9	10
≥ 0.15.8, ≤ 0.16	9	11
0.17, 0.18	9	12
≥ 0.19, ≤ 0.20.2	13	13
≥ 0.20.3, ≤ 0.24	13	14
≥ 0.25	13	15

The Tree-sitter library is generally backwards-compatible with languages generated using older CLI versions, but is not forwards-compatible. You cannot use a parser with a newer ABI version than the library supports.

Checking Compatibility

When setting a language on a parser, Tree-sitter automatically checks ABI compatibility:

C

#include <tree_sitter/api.h>

TSParser *parser = ts_parser_new();
const TSLanguage *language = tree_sitter_json();

bool success = ts_parser_set_language(parser, language);

if (!success) {
    uint32_t abi_version = ts_language_abi_version(language);
    fprintf(stderr,
            "Error: Parser has ABI version %u, but library supports %u-%u\n",
            abi_version,
            TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION,
            TREE_SITTER_LANGUAGE_VERSION);
    ts_parser_delete(parser);
    return 1;
}

Generating Parsers with Specific ABI Versions

By default, the Tree-sitter CLI will generate parsers using the latest available ABI for that version. However, you can select an older ABI using the --abi option:

# Generate a parser with ABI version 13
tree-sitter generate --abi 13

# Generate a parser with the default (latest) ABI
tree-sitter generate

The ABI version range supported by the CLI can be smaller than for the library. When a new ABI version is released, older versions will be phased out over a deprecation period. During this period, you can still load parsers with the old ABI, but you can no longer generate parsers with it.

When to Regenerate Parsers

You should regenerate your parser when:

1. Upgrading Tree-sitter

   When you upgrade to a major or minor version of Tree-sitter that introduces a new ABI version, regenerate your parsers to take advantage of new features and optimizations.

2. Supporting older libraries

   If you need your parser to work with older versions of the Tree-sitter library, generate it with an older ABI version using --abi.

3. ABI compatibility errors

   If users report ABI version mismatch errors, you may need to regenerate your parser with a compatible ABI version.

ABI Version Changes

ABI versions may change when Tree-sitter introduces:

• New language features in the grammar DSL
• Changes to the generated parser structure
• New runtime capabilities
• Performance improvements requiring structural changes

Major ABI changes

Some notable ABI version changes:

• ABI 13 (Tree-sitter 0.19): Major rewrite of the runtime for improved performance
• ABI 14 (Tree-sitter 0.20.3): Added support for language metadata
• ABI 15 (Tree-sitter 0.25): Enhanced query capabilities and optimizations

Best Practices

Keep Libraries Updated

Regularly update your Tree-sitter library to get the latest features and bug fixes.

Document Requirements

Clearly document which Tree-sitter version your parser requires.

Test Compatibility

Test your parser with the minimum supported Tree-sitter version.

Automate Regeneration

Use CI/CD to automatically regenerate parsers when Tree-sitter is updated.

Package.json Example

If you’re publishing a parser as an npm package, specify the Tree-sitter version requirement:

package.json

{
  "name": "tree-sitter-mylanguage",
  "version": "1.0.0",
  "main": "bindings/node",
  "peerDependencies": {
    "tree-sitter": "^0.25.0"
  },
  "devDependencies": {
    "tree-sitter-cli": "^0.25.0"
  },
  "tree-sitter": [
    {
      "scope": "source.mylanguage",
      "file-types": ["mylang"],
      "highlights": "queries/highlights.scm"
    }
  ]
}

Cargo.toml Example

For Rust projects, specify the version in Cargo.toml:

Cargo.toml

[package]
name = "tree-sitter-mylanguage"
version = "1.0.0"
edition = "2021"

[dependencies]
tree-sitter = "~0.25"
tree-sitter-language = "~0.1"

[build-dependencies]
cc = "1.0"

Troubleshooting

Error: Language version X is too old

This means your parser was generated with an ABI version older than the minimum supported by the current Tree-sitter library.

Solution: Regenerate your parser with the Tree-sitter CLI:

tree-sitter generate

Error: Language version X is too new

This means your parser was generated with an ABI version newer than what the current Tree-sitter library supports.

Solution: Either:

1. Update your Tree-sitter library to a newer version
2. Regenerate the parser with an older ABI version:

tree-sitter generate --abi 13

My parser works locally but not for users

Users may have an older version of Tree-sitter installed.

Solution:

1. Check what Tree-sitter version your users have
2. Either ask users to upgrade, or regenerate with a compatible ABI:

tree-sitter generate --abi 13

3. Document the minimum required Tree-sitter version

How do I check my parser's ABI version?

You can check the ABI version programmatically or by looking at the generated parser.c file:

// In parser.c
extern const TSLanguage *tree_sitter_mylanguage(void) {
  static const TSLanguage language = {
    .version = LANGUAGE_VERSION,  // This is the ABI version
    // ...
  };
  return &language;
}

Version Detection Script

Here’s a script to check ABI compatibility:

check_abi.py

import json
import subprocess

def check_parser_abi(parser_path):
    # Get Tree-sitter library version
    result = subprocess.run(
        ['tree-sitter', '--version'],
        capture_output=True,
        text=True
    )
    lib_version = result.stdout.strip().split()[1]
    
    # Get parser ABI version (would need to parse parser.c)
    print(f"Tree-sitter library version: {lib_version}")
    print("Checking parser compatibility...")
    
    # Map library versions to supported ABI ranges
    version_map = {
        '0.25': (13, 15),
        '0.24': (13, 14),
        '0.23': (13, 14),
        # ... more versions
    }
    
    # Check compatibility
    for lib_ver, (min_abi, max_abi) in version_map.items():
        if lib_version.startswith(lib_ver):
            print(f"Library supports ABI {min_abi}-{max_abi}")
            break

if __name__ == '__main__':
    check_parser_abi('.')

Further Reading

Creating Parsers

Learn how to create your own Tree-sitter parser

CLI Documentation

Read about the tree-sitter generate command

Contributing

Contribute to Tree-sitter development

For the most up-to-date information about ABI versions, always check the official Tree-sitter repository and release notes.