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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.482s · 60MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ExtractorModel
✓ from maco.model import ExtractorModel
Extractor
✓ from maco.extractor import Extractor
run_extractor
✓ from maco.collector import run_extractor
This quickstart demonstrates how to define a custom Maco extractor, process a sample file with it, and retrieve the extracted `ExtractorModel` results.
import os
from maco.model import ExtractorModel
from maco.extractor import Extractor
from maco.collector import run_extractor
# Define a simple Maco Extractor
class MySimpleExtractor(Extractor):
# Yara rules can be defined here as a bytes object
# rules = b'rule my_rule { strings: $a = "test_data" condition: $a }'
def run(self, sample: bytes, **kwargs) -> ExtractorModel:
# Example: if a specific string is found, set a property in the model
if b"hello maco" in sample:
model = ExtractorModel(family="GreetingMalware")
model.add_tag("found_greeting")
model.add_string(value="hello maco", context="sample_content")
return model
# All extractors must return an ExtractorModel, even if no config is found
return ExtractorModel(family="Unknown")
# Create a dummy file for the extractor to process
sample_content = b"This is some test_data with hello maco inside."
sample_path = "test_sample.bin"
with open(sample_path, "wb") as f:
f.write(sample_content)
try:
# Run the extractor against the sample file
# 'extractors' expects a list of Extractor classes
results = run_extractor(extractors=[MySimpleExtractor], sample_path=sample_path)
# Print the results
print(f"Extractor results for {sample_path}:")
for result in results:
print(f" Family: {result.family}")
print(f" Tags: {result.tags}")
print(f" Strings: {[s.value for s in result.strings]}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the dummy file
if os.path.exists(sample_path):
os.remove(sample_path)
maco-extractor --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'maco'
The `maco-extractor` package, or its main `maco` module, is not installed or not accessible in the current Python environment.
fixInstall the library using pip: `pip install maco-extractor`
AttributeError: module 'maco' has no attribute 'Extractor'
This typically occurs when a user has installed the `maco-model` package (which only provides the data model) but is attempting to access components like `Extractor` or `Collector` that are part of the full `maco-extractor` framework.
fixIf you need the full framework, uninstall `maco-model` if it's installed, then install the complete `maco-extractor` package: `pip uninstall maco-model && pip install maco-extractor`
maco: command not found
The `maco` command-line interface (CLI) tool, which is installed with `maco-extractor`, is not in your system's PATH, or the Python environment where it was installed is not currently active.
fixActivate the Python environment where `maco-extractor` is installed, or run the CLI tool explicitly using `python -m maco.cli`.
Upgrade
Version history
1.3.1latest on PyPI · released Jun 10, 2026
Audit
Dependencies
yara-xrequiredCore component for defining and processing YARA rules within extractors.