Install & Compatibility
Where this runs
tested against v1.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.062s · 21.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.064s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UnleashEngine
✓ from yggdrasil_engine.engine import UnleashEngine
While this is the direct import, users typically interact with UnleashClient, which uses this internally. Direct instantiation of UnleashEngine is uncommon for end-users.
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`.
import os
from UnleashClient import UnleashClient
# NOTE: yggdrasil-engine is an internal dependency of UnleashClient.
# Most users will interact with UnleashClient, which leverages yggdrasil-engine
# for high-performance feature flag evaluation.
# Configure UnleashClient (using environment variables for sensitive data)
unleash_url = os.environ.get('UNLEASH_URL', 'http://localhost:4242/api')
unleash_app_name = os.environ.get('UNLEASH_APP_NAME', 'my-python-app')
unleash_instance_id = os.environ.get('UNLEASH_INSTANCE_ID', 'my-instance')
unleash_api_token = os.environ.get('UNLEASH_API_TOKEN', '')
client = UnleashClient(
url=unleash_url,
app_name=unleash_app_name,
instance_id=unleash_instance_id,
custom_headers={'Authorization': unleash_api_token} if unleash_api_token else None
)
# Initialize the client. This will fetch feature flags from the Unleash server.
client.initialize_client()
# Check if a feature flag is enabled
feature_name = "my-awesome-feature"
is_enabled = client.is_enabled(feature_name)
if is_enabled:
print(f"Feature '{feature_name}' is enabled!")
else:
print(f"Feature '{feature_name}' is disabled.")
# Get a variant for a feature flag
variant = client.get_variant("my-variant-feature", context={'userId': 'user123'})
print(f"Variant for 'my-variant-feature': {variant['name']}")
# Clean up resources when done
client.destroy()
Debug
Known issues
gotchaDirect 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.fixUse `UnleashClient` for feature flag management; `yggdrasil-engine` is an underlying dependency that handles the efficient evaluation.
affects: All versions
gotchaRust 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.fixFor development from source, ensure Rust and `maturin` are installed. For general usage, `pip install yggdrasil-engine` should suffice by leveraging pre-built wheels.
affects: All versions (when building from source)
gotchaEvaluation 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.fixFocus on optimizing `UnleashClient`'s refresh intervals and caching strategies to minimize network calls, rather than concerns about the `yggdrasil-engine`'s internal evaluation speed.
affects: All versions
breakingBreaking 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.fixRefer to the `UnleashClient` migration documentation for guidance when upgrading, especially between major versions.
affects: Potentially across major `UnleashClient` versions
Errors
Common errors & fixes
error: can't find Rust compiler
The Rust toolchain is not installed or not in your system's PATH, which is required to compile `yggdrasil-engine`'s Rust components during installation.
fixInstall Rust by following the instructions at rustup.rs (e.g., `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`).
ModuleNotFoundError: No module named 'yggdrasil_engine'
The `yggdrasil-engine` package is not installed in your current Python environment.
fixInstall the package using pip: `pip install yggdrasil-engine`.
ImportError: cannot import name 'YggdrasilEngine' from 'yggdrasil_engine'
The main class for the Unleash evaluation engine is named `Engine` (with a capital 'E'), not `YggdrasilEngine`.
fixUse the correct class name for import: `from yggdrasil_engine import Engine`.
TypeError: 'type' object is not callable
The `yggdrasil_engine.Engine` class is not directly instantiable using `()` syntax; it requires a specific factory method for initialization.
fixUse the `new_engine` static method to create an engine instance: `engine_instance = Engine.new_engine(json_config, initial_state)`.
Upgrade
Version history
1.3.1latest on PyPI · released Jun 24, 2026
Audit
Dependencies
pythonrequiredRequires specific Python versions for compatibility with PyO3 bindings.
UnleashClientoptionalyggdrasil-engine is typically an internal dependency of the UnleashClient SDK for actual feature flag management.