Unity-Technologies/ml-agents · error · UnityEnvironmentException

The communication API version is not compatible between Unit

Error message

The communication API version is not compatible between Unity and python. Python API: {UnityEnvironment.API_VERSION}, Unity API: {unity_com_ver}.
 Please find the versions that work best together from our release page.
https://github.com/Unity-Technologies/ml-agents/releases

What it means

Static method UnityEnvironment._raise_version_exception throws UnityEnvironmentException when the communication API version reported by the Unity side of the communicator does not match UnityEnvironment.API_VERSION on the Python side. ml-agents requires both halves to speak the same protocol version. It directs the user to the release notes to find matching versions.

Source

Thrown at ml-agents-envs/mlagents_envs/environment.py:83

    #  * 1.3.0 - support action spaces with both continuous and discrete actions.
    #  * 1.4.0 - support training analytics sent from python trainer to the editor.
    #  * 1.5.0 - support variable length observation training and multi-agent groups.
    API_VERSION = "1.5.0"

    # Default port that the editor listens on. If an environment executable
    # isn't specified, this port will be used.
    DEFAULT_EDITOR_PORT = 5004

    # Default base port for environments. Each environment will be offset from this
    # by it's worker_id.
    BASE_ENVIRONMENT_PORT = 5005

    # Command line argument used to pass the port to the executable environment.
    _PORT_COMMAND_LINE_ARG = "--mlagents-port"

    @staticmethod
    def _raise_version_exception(unity_com_ver: str) -> None:
        raise UnityEnvironmentException(
            f"The communication API version is not compatible between Unity and python. "
            f"Python API: {UnityEnvironment.API_VERSION}, Unity API: {unity_com_ver}.\n "
            f"Please find the versions that work best together from our release page.\n"
            "https://github.com/Unity-Technologies/ml-agents/releases"
        )

    @staticmethod
    def _check_communication_compatibility(
        unity_com_ver: str, python_api_version: str, unity_package_version: str
    ) -> bool:
        unity_communicator_version = StrictVersion(unity_com_ver)
        api_version = StrictVersion(python_api_version)
        if unity_communicator_version.version[0] == 0:
            if (
                unity_communicator_version.version[0] != api_version.version[0]
                or unity_communicator_version.version[1] != api_version.version[1]
            ):
                # Minor beta versions differ.

View on GitHub (pinned to 3ecb446f75)

Solutions

  1. Align versions: install the Python package matching the Unity ML-Agents release (e.g. pip install mlagents==<matching-release>).
  2. Rebuild the Unity executable with the same ML-Agents release as the Python side.
  3. Check the ml-agents releases page for the version compatibility table.
  4. Pin both sides (requirements.txt and Unity PackageManifest) to the same release to avoid drift.

Example fix

// before (shell)
pip install mlagents  # latest python, but Unity build uses release 18
# UnityEnvironmentException: API version not compatible

// after (shell)
pip install mlagents==0.30.0  # matches Unity ML-Agents release 18
Defensive patterns

Strategy: validation

Validate before calling

from mlagents_envs.environment import UnityEnvironment
import mlagents
print('Python API version:', UnityEnvironment.API_VERSION)
print('mlagents package:', mlagents.__version__)
# Confirm this matches the ML-Agents release used to build the Unity executable.

Try / catch

from mlagents_envs.exception import UnityEnvironmentException
try:
    env = UnityEnvironment(file_name='env.x86_64')
except UnityEnvironmentException as e:
    if 'API version is not compatible' in str(e):
        print('Reinstall mlagents at the version matching your Unity build.')
    raise

Prevention

When it happens

Trigger: Launching or connecting to a Unity build created with an ml-agents release whose communicator API version differs from the installed mlagents_envs Python package; the handshake compares unity_com_ver against UnityEnvironment.API_VERSION and calls this method on mismatch.

Common situations: pip-installed mlagents at one version while the Unity project uses the ML-Agents package/commlib of another release; upgrading only the Python side; connecting an old prebuilt environment to a newly upgraded training stack.

Related errors

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/57866f3abdefef7a. Report an issue: GitHub.