> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/retis-org/retis/llms.txt
> Use this file to discover all available pages before exploring further.

# Compatibility

> Compatibility guarantees and version support for Retis APIs and data formats

Retis exposes data and APIs in different ways, including event storage at collection time and the Python API (built-in interpreter and library). This page covers what is considered stable in terms of compatibility across versions and what is not.

## Events File Format

When collecting events, Retis can store events in a file for later post-processing (`retis.data` by default).

### Format Stability

<Warning>
  The event file format itself is **not guaranteed to be stable** across time in any way. It is not recommended to use it directly.
</Warning>

### Forward Compatibility

Starting with Retis `1.5.0`, events collected and stored with a version of Retis can be read with newer versions of Retis, **across a given major version**.

<Note>
  Events collected with Retis v1.5.0 can be read with Retis v1.6.x, but might not work with Retis v2.y.x.
</Note>

### Examples

<CodeGroup>
  ```bash Same Major Version (Works) theme={null}
  # Collect with v1.5.0
  retis-1.5.0 collect -o events.data

  # Read with v1.6.0
  retis-1.6.0 print -i events.data
  # ✓ This works - same major version
  ```

  ```bash Different Major Version (May Not Work) theme={null}
  # Collect with v1.5.0
  retis-1.5.0 collect -o events.data

  # Read with v2.0.0
  retis-2.0.0 print -i events.data
  # ✗ This might fail - different major version
  ```
</CodeGroup>

### Recommendations

* **Use the same major version** for collecting and processing events
* **Don't parse the binary format directly** - use Retis commands or Python API
* **Archive events with version info** - include the Retis version when archiving event files
* **Re-collect for major upgrades** - if upgrading to a new major version, plan to re-collect events

## Python API and Events

Python can be used to post-process events, with both events and an API exposed for custom processing.

<Warning>
  The Python API is **not considered stable** across releases at the moment.
</Warning>

### Current Status

* **Stability**: Unstable - subject to change between releases
* **Compatibility**: Not guaranteed between versions
* **Documentation**: See [Python bindings documentation](/advanced/python-bindings)

### Working with the Python API

While the Python API is evolving:

* Expect breaking changes between releases
* Pin your Retis version if using Python processing in production
* Test your Python scripts after upgrading Retis
* Check release notes for API changes

<Note>
  The Retis team is working toward stabilizing the Python API in future releases. Community feedback on the API design is welcome.
</Note>

## Command-Line Interface

### Stability Guarantees

The Retis command-line interface follows these compatibility guidelines:

* **Commands**: Core commands (`collect`, `print`, `sort`, `pcap`) are stable
* **Options**: Common options are generally stable within major versions
* **Output format**: Text output format may change between minor versions
* **Exit codes**: Standard exit codes (0 for success, non-zero for errors) are stable

### Deprecation Policy

When commands or options are deprecated:

1. A warning is shown in the current release
2. The feature remains functional for at least one minor version
3. Removal occurs in the next major version

## Kernel Compatibility

Retis is designed to work with modern Linux kernels that support eBPF and BTF.

### Minimum Requirements

* **Kernel version**: Generally, kernels >= 5.x with BTF support
* **eBPF features**: Full BPF support with BTF type information
* **Configuration**: See [Requirements](/requirements) for kernel config details

### Testing

Retis is regularly tested on:

* Recent Fedora releases (including Rawhide)
* RHEL 8.6+ and RHEL 9
* CentOS Stream 8 and 9
* Ubuntu Jammy

<Note>
  While Retis should work on other distributions meeting the kernel requirements, the distributions listed above receive regular testing and validation.
</Note>

## Upgrade Guidelines

### Minor Version Upgrades (e.g., 1.5.x → 1.6.x)

<Steps>
  <Step title="Review release notes">
    Check for any new features or deprecation warnings.
  </Step>

  <Step title="Test existing workflows">
    Verify that your existing commands and profiles still work.
  </Step>

  <Step title="Update scripts if needed">
    If you use the Python API, test and update your scripts.
  </Step>
</Steps>

### Major Version Upgrades (e.g., 1.x → 2.x)

<Steps>
  <Step title="Review breaking changes">
    Major versions may include breaking changes - carefully review the changelog.
  </Step>

  <Step title="Plan for re-collection">
    Old event files may not be compatible - plan to re-collect data if needed.
  </Step>

  <Step title="Update Python scripts">
    The Python API may have significant changes requiring script updates.
  </Step>

  <Step title="Test in non-production first">
    Validate the upgrade in a test environment before production use.
  </Step>
</Steps>

## Getting Help

If you encounter compatibility issues:

* Check the [GitHub issues](https://github.com/retis-org/retis/issues) for known problems
* Report new compatibility issues on GitHub
* Include your Retis version (`retis --version`) and kernel version (`uname -r`) when reporting issues


Built with [Mintlify](https://mintlify.com).