Install & Compatibility
Where this runs
tested against v3.0.2 · 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.602s · 28.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.568s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Indicator
✓ from stix2 import Indicator
✗ import stix2
obj = stix2.Indicator()
Implicit imports can break across major releases as the default STIX version supported by the library may change. It's recommended to import specific classes or explicitly reference versioned modules (e.g., `stix2.v21.Indicator`).
parse
✓ from stix2 import parse
serialize
✓ from stix2 import serialize
v21 (for explicit versioning)
✓ from stix2 import v21
obj = v21.Indicator()
This quickstart demonstrates how to create a STIX Indicator object, serialize it to pretty-printed JSON, and parse a STIX JSON string back into a Python object. It uses the `Indicator` class for object creation and `serialize` and `parse` functions for data interchange.
from stix2 import Indicator, parse, serialize
from datetime import datetime, timezone
# Create a STIX Indicator object
indicator = Indicator(
name="File hash for malware variant",
indicator_types=["malicious-activity"],
pattern_type="stix",
pattern="[file:hashes.md5 = 'd41d8cd98f00b204e9800998ecf8427e']",
valid_from=datetime.now(timezone.utc)
)
# Serialize the STIX object to JSON
serialized_indicator = serialize(indicator, pretty=True)
print("\nSerialized Indicator:")
print(serialized_indicator)
# Parse a STIX JSON string back into a Python object
json_string = '''{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--dbcbd659-c927-4f9a-994f-0a2632274394",
"created": "2017-09-26T23:33:39.829Z",
"modified": "2017-09-26T23:33:39.829Z",
"name": "Another malware hash",
"indicator_types": ["malicious-activity"],
"pattern_type": "stix",
"pattern_version": "2.1",
"pattern": "[file:hashes.md5 = 'abcdef1234567890abcdef1234567890']",
"valid_from": "2017-09-26T23:33:39.829952Z"
}'''
parsed_indicator = parse(json_string)
print("\nParsed Indicator Name:", parsed_indicator.name)
Debug
Known issues
breakingThe `stix2` library now requires Python 3.10 or higher. Older Python versions are no longer supported.fixUpgrade your Python environment to 3.10 or newer. Ensure your `pyproject.toml` or `setup.py` reflects this requirement.
affects: 3.0.0 and later
breakingImplicit imports (e.g., `import stix2; stix2.Indicator()`) can lead to breaking changes across major releases of `stix2` as the default STIX specification version supported by the library may be updated.fixExplicitly import specific STIX object types (e.g., `from stix2 import Indicator`) or specify the STIX version using versioned modules (e.g., `from stix2 import v21; obj = v21.Indicator()`).
affects: All major versions (e.g., between v2.x and v3.x)
deprecatedCustom properties in STIX 2.0 were deprecated in STIX 2.1 in favor of the `property-extension` mechanism. While the library supports parsing old custom properties for backward compatibility, new content should use extensions.fixFor new custom content, define and use STIX Extensions instead of directly adding custom properties. Refer to the `stix2` documentation on custom content and extensions.
affects: STIX 2.1 specification and `stix2` library versions supporting it (v3.0.0+)
gotchaSTIX objects created with the `stix2` library are immutable by design. All properties must be provided during object instantiation and cannot be changed afterward.fixTo 'modify' an object, create a new object instance with the desired changes, often leveraging the `new_version()` method for versioning STIX objects appropriately.
affects: All versions
gotchaID generation differs between STIX Domain Objects (SDOs) and STIX Relationship Objects (SROs) which use random v4 UUIDs, and STIX Cyber Observable Objects (SCOs) which use deterministic v5 UUIDs. Changing ID-contributing properties for an SCO will result in a new ID.fixBe aware of the ID generation behavior when creating and versioning objects, especially SCOs. If an SCO's ID-contributing properties change, it's considered a new object, not a minor version update.
affects: All versions
breakingThe `six` compatibility library dependency was dropped in `stix2` v3.0.0. This might affect applications relying on `six` for Python 2/3 compatibility within their `stix2` integration.fixEnsure your codebase is fully Python 3 compatible and no longer relies on `six` for `stix2`-related operations. This change supports the library's Python 3.10+ requirement.
affects: 3.0.0 and later
Upgrade
Version history
3.0.2latest on PyPI · released Feb 12, 2026
Audit
Dependencies
pythonrequiredRequired Python version.