Install & Compatibility
Where this runs
tested against v1.1.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.95 runs
installs and imports cleanly · install 0.0s · import 0.410s · 21.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.378s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Snowplow
✓ from snowplow_tracker import Snowplow
Preferred entry point for initializing a tracker with default emitter and subject settings.
Tracker
✓ from snowplow_tracker import Tracker
✗ tracker = Tracker('collector.example.com')
While direct instantiation of Tracker, Emitter, and Subject is possible, Snowplow.create_tracker is recommended for most use cases as it simplifies initialization.
Emitter
✓ from snowplow_tracker import Emitter
✗ emitter = Emitter('collector.example.com')
See note for Tracker; direct instantiation of components is an older pattern that is often replaced by `Snowplow.create_tracker`.
Subject
✓ from snowplow_tracker import Subject
✗ subject = Subject()
See note for Tracker; direct instantiation of components is an older pattern that is often replaced by `Snowplow.create_tracker`.
This quickstart demonstrates how to initialize the Snowplow tracker and send various event types, including page views, structured events, and custom self-describing events. Ensure `SNOWPLOW_COLLECTOR_ENDPOINT` is set in your environment or replace `'collector.example.com'` with your actual Snowplow collector URI.
import os
from snowplow_tracker import Snowplow, SelfDescribingJson
# Configure your Snowplow collector endpoint
COLLECTOR_ENDPOINT = os.environ.get('SNOWPLOW_COLLECTOR_ENDPOINT', 'collector.example.com')
# Initialize the Snowplow tracker
# The namespace is mandatory and helps identify events from this tracker instance.
tracker = Snowplow.create_tracker(namespace='my-app-tracker', endpoint=COLLECTOR_ENDPOINT)
# Track a page view event
tracker.track_page_view(
page_url='http://www.example.com/home',
page_title='Homepage',
referrer='http://www.example.com/previous'
)
# Track a structured event
tracker.track_struct_event(
category='engagement',
action='click',
label='hero-button',
property='primary-cta',
value=1.0
)
# Track an unstructured event (Self-Describing Event)
custom_event_schema = SelfDescribingJson(
'iglu:com.example/my_custom_event/jsonschema/1-0-0',
{'feature': 'new-feature', 'version': '1.0'}
)
tracker.track_self_describing_event(custom_event_schema)
print(f"Events tracked to {COLLECTOR_ENDPOINT} (check your Snowplow pipeline). ")
Debug
Known issues
gotchaWhen initializing the tracker, the `namespace` argument is mandatory. Failing to provide it will result in an error or default behavior that might not be desired for identifying events from specific tracker instances.fixAlways provide a unique `namespace` argument when calling `Snowplow.create_tracker` or directly instantiating `Tracker`.
affects: All versions 1.x.x
gotchaThe documentation mentions that `track_screen_view()` and `track_unstruct_event()` were not fully supported in the Snowplow data pipeline's enrichment, storage, or analytics stages in older versions (e.g., v0.2, v0.4), meaning events would be logged but not processed further.fixEnsure you are using a recent version of `snowplow-tracker` (1.x.x) and that your Snowplow data pipeline is up-to-date to fully process all event types, especially custom unstructured events.
affects: Older versions (prior to 1.x.x)
breakingThe Snowplow ecosystem, particularly for mobile trackers (iOS and Android), underwent significant API changes from version 1.x to 2.0, with `Snowplow.createTracker` becoming the new entry point and the old API being deprecated. While `snowplow-tracker` for Python is currently at version 1.x.x, future major releases might introduce similar breaking changes.fixAlways consult the official migration guides when upgrading to a new major version of `snowplow-tracker` to understand potential API changes and necessary code adjustments. For the current 1.x.x Python tracker, refer to the 'Upgrading to newer versions' section in the Python tracker SDK documentation.
affects: Future major versions (e.g., 2.x.x)
breakingThe `track_struct_event` method does not accept a keyword argument named `property`. Using an incorrect keyword argument will result in a TypeError and application crash.fixReview the official Snowplow Python tracker documentation for the `track_struct_event` method to ensure correct argument names and usage. Avoid using 'property' as a keyword argument, and instead use the documented parameter (e.g., 'properties').
affects: All versions 1.x.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'snowplow_tracker'
The 'snowplow-tracker' library is not installed in the current Python environment, or the environment is not correctly activated.
fixpip install snowplow-tracker
TypeError: emitters must be a list of Emitter objects
The `emitters` argument provided to the `Tracker` constructor was not a list containing `Emitter` instances.
fixfrom snowplow_tracker import Emitter, Tracker
emitter = Emitter('collector.example.com')
tracker = Tracker([emitter]) ValueError: Self-describing event payload must contain 'schema' and 'data' fields.
A self-describing event or custom context dictionary was provided without the required 'schema' and 'data' keys, or they were malformed.
fixevent_json = {"schema": "iglu:com.example/my_event/jsonschema/1-0-0", "data": {"key": "value"}}
tracker.track_self_describing_event(event_json) TypeError: tracker_name must be a string
The `tracker_name` parameter during `Tracker` initialization was provided with a non-string value.
fixfrom snowplow_tracker import Emitter, Tracker
emitter = Emitter('collector.example.com')
tracker = Tracker([emitter], tracker_name="my_application") Upgrade
Version history
1.1.0latest on PyPI · released Feb 21, 2025
Audit
Dependencies
requestsrequiredHTTP library for sending events.
typing-extensionsrequiredBackported type hints for Python.