Install & Compatibility
Where this runs
tested against v1.17.0 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.000s · 50MB
48MB installed
● package 48MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
yara_x
✓ import yara_x
✗ import yara
YARA-X is a distinct library from the original YARA-Python. The module name is `yara_x`, not `yara`.
This quickstart demonstrates compiling YARA-X rules from a string and then scanning data. It covers both the simple `yara_x.compile()` function and using the `Compiler` object for more advanced scenarios like managing namespaces.
import yara_x
rules_source = '''
rule example_rule {
strings:
$a = "foobar"
condition:
$a
}
'''
# Compile the rules
rules = yara_x.compile(rules_source)
# Scan data
data_to_scan = b"This is some data containing foobar for testing."
results = rules.scan(data_to_scan)
if results:
print(f"Matches found: {results}")
else:
print("No matches.")
# Example with a Compiler object for more complex scenarios
compiler = yara_x.Compiler()
compiler.add_source(rules_source, origin="my_rules")
compiled_rules_obj = compiler.build()
scan_results_obj = compiled_rules_obj.scan(b"Another foobar string.")
if scan_results_obj:
print(f"Matches found with Compiler: {scan_results_obj}")
yarax --version
Debug
Known issues
breakingYARA-X enforces stricter regular expression syntax compared to the original YARA. Certain constructs that YARA previously accepted (e.g., invalid escape sequences treated as literals, unescaped special characters inferred from context) will now raise compilation errors in YARA-X.fixReview and update YARA rules to conform to stricter regex syntax. The `Compiler` object has a `relaxed_re_syntax` argument that can be set to `True` to mimic YARA's behavior, but this is generally not recommended for new rules.
affects: All YARA-X versions
gotchaYARA-X is a completely new implementation (in Rust) and is not a drop-in replacement for the `yara-python` library. The Python module is imported as `yara_x`, not `yara`. Users migrating from `yara-python` will need to update import statements and be aware of API differences, though the core compilation and scanning workflow is similar.fixAlways use `import yara_x`. Consult the YARA-X Python documentation for API specifics and any behavioral changes compared to `yara-python`.
affects: All YARA-X versions
gotchaThe behavior of the `strings` field in the `Match` object significantly changed in `yara-python` versions 4.3.0 and later (from an array of tuples to `yara.StringMatch` objects). While this is specific to `yara-python`, users familiar with that library's older API might incorrectly expect similar `Match` object structures or behaviors when adapting to YARA-X. YARA-X's match result structure is different.fixFamiliarize yourself with the `yara_x` scan result object structure, particularly how matched strings are represented, as it differs from both old and new `yara-python` versions.
affects: N/A (applies to yara-python, but a common migration footgun)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'yara_x'
The 'yara-x' Python package is not installed in the current environment or the Python interpreter cannot find it.
fixInstall the package using pip: `pip install yara-x`
ImportError: cannot import name 'Compiler' from 'yara_x'
The `Compiler` class is located in the `yara_x.compiler` submodule, but it's being incorrectly imported directly from the top-level `yara_x` package.
fixImport `Compiler` from its specific submodule: `from yara_x.compiler import Compiler`
yara_x.YaraXError: syntax error at line X, column Y
The YARA rule string provided to the `Compiler.add_source()` method contains a syntax error.
fixReview and correct the YARA rule syntax, ensuring all sections (e.g., `strings`, `condition`) are present and correctly formatted. Example: `compiler.add_source('rule example { strings: $a = "abc" condition: $a }')` TypeError: expected bytes, got str
The `scanner.scan_data()` method was called with a string object, but it explicitly requires a bytes object for the data to be scanned.
fixEncode the string data into bytes before passing it to `scan_data()`: `scanner.scan_data("your data here".encode('utf-8'))` ERROR: No matching distribution found for yara-x
Pip could not find a pre-compiled wheel package for your specific Python version, operating system, or architecture, or your environment is not supported.
fixEnsure your Python version (3.9+) and operating system (Linux, macOS, Windows) are supported. Upgrade pip: `python -m pip install --upgrade pip`. If the issue persists, your environment might not be directly compatible with the available wheels.
Upgrade
Version history
1.17.0latest on PyPI · released May 27, 2026
Audit
Dependencies
No dependency data recorded yet.