{"id":4333,"library":"yggdrasil-engine","title":"Unleash Yggdrasil Engine","description":"yggdrasil-engine is a Python package that provides the core evaluation logic for Unleash feature flags. Implemented in Rust and exposed to Python via PyO3, it offers a high-performance, consistent, and cross-language engine for feature flag evaluation. It is primarily an internal dependency of the UnleashClient Python SDK, ensuring fast and reliable local flag evaluation. The current version is 1.3.0. Releases are typically tied to updates in the Unleash feature flag system.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/Unleash/yggdrasil","tags":["feature flags","unleash","rust","pyo3","sdk","backend"],"install":[{"cmd":"pip install yggdrasil-engine","lang":"bash","label":"Install yggdrasil-engine"}],"dependencies":[{"reason":"Requires specific Python versions for compatibility with PyO3 bindings.","package":"python","optional":false},{"reason":"yggdrasil-engine is typically an internal dependency of the UnleashClient SDK for actual feature flag management.","package":"UnleashClient","optional":true}],"imports":[{"note":"While this is the direct import, users typically interact with UnleashClient, which uses this internally. Direct instantiation of UnleashEngine is uncommon for end-users.","symbol":"UnleashEngine","correct":"from yggdrasil_engine.engine import UnleashEngine"}],"quickstart":{"code":"import os\nfrom UnleashClient import UnleashClient\n\n# NOTE: yggdrasil-engine is an internal dependency of UnleashClient.\n# Most users will interact with UnleashClient, which leverages yggdrasil-engine\n# for high-performance feature flag evaluation.\n\n# Configure UnleashClient (using environment variables for sensitive data)\nunleash_url = os.environ.get('UNLEASH_URL', 'http://localhost:4242/api')\nunleash_app_name = os.environ.get('UNLEASH_APP_NAME', 'my-python-app')\nunleash_instance_id = os.environ.get('UNLEASH_INSTANCE_ID', 'my-instance')\nunleash_api_token = os.environ.get('UNLEASH_API_TOKEN', '')\n\nclient = UnleashClient(\n    url=unleash_url,\n    app_name=unleash_app_name,\n    instance_id=unleash_instance_id,\n    custom_headers={'Authorization': unleash_api_token} if unleash_api_token else None\n)\n\n# Initialize the client. This will fetch feature flags from the Unleash server.\nclient.initialize_client()\n\n# Check if a feature flag is enabled\nfeature_name = \"my-awesome-feature\"\nis_enabled = client.is_enabled(feature_name)\n\nif is_enabled:\n    print(f\"Feature '{feature_name}' is enabled!\")\nelse:\n    print(f\"Feature '{feature_name}' is disabled.\")\n\n# Get a variant for a feature flag\nvariant = client.get_variant(\"my-variant-feature\", context={'userId': 'user123'})\nprint(f\"Variant for 'my-variant-feature': {variant['name']}\")\n\n# Clean up resources when done\nclient.destroy()\n","lang":"python","description":"The `yggdrasil-engine` library serves as a low-level, high-performance evaluation engine. End-users typically interact with the higher-level `UnleashClient` Python SDK, which abstracts away the complexities of the underlying engine. This quickstart demonstrates how to use `UnleashClient` to evaluate feature flags, which implicitly utilizes `yggdrasil-engine`."},"warnings":[{"fix":"Use `UnleashClient` for feature flag management; `yggdrasil-engine` is an underlying dependency that handles the efficient evaluation.","message":"Direct Usage vs. UnleashClient: Most users should interact with the `UnleashClient` Python SDK, which internally uses `yggdrasil-engine`. Direct interaction with `yggdrasil-engine`'s API is uncommon and may expose lower-level details not intended for general application development.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For development from source, ensure Rust and `maturin` are installed. For general usage, `pip install yggdrasil-engine` should suffice by leveraging pre-built wheels.","message":"Rust Toolchain for Source Builds: While `yggdrasil-engine` provides pre-compiled Python wheels, building from source or contributing to the project requires a Rust toolchain and `maturin` for PyO3 bindings. Standard `pip install` typically handles pre-built binaries.","severity":"gotcha","affected_versions":"All versions (when building from source)"},{"fix":"Focus on optimizing `UnleashClient`'s refresh intervals and caching strategies to minimize network calls, rather than concerns about the `yggdrasil-engine`'s internal evaluation speed.","message":"Evaluation Performance Context: `yggdrasil-engine` offers evaluation in hundreds of nanoseconds, making it extremely fast. However, the overall performance of feature flag checks in an application will largely be dominated by network latency (fetching flags from the Unleash server) rather than the engine's evaluation speed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `UnleashClient` migration documentation for guidance when upgrading, especially between major versions.","message":"Breaking changes in the UnleashClient SDK (e.g., migration to v6) may indirectly impact how `yggdrasil-engine` is consumed or the expected format of inputs if the `UnleashClient`'s internal API changes its interaction with the engine. Always consult the `UnleashClient` migration guides when upgrading.","severity":"breaking","affected_versions":"Potentially across major `UnleashClient` versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}