Snowplow event tracker for Python

1.1.0 verified Tue May 12 auth: no python install: verified

The Snowplow Python Tracker allows you to collect and track event data from your Python applications, games, and web servers/frameworks, including Django. It provides a robust way to implement analytics by defining subjects, emitters, and trackers to send events to a Snowplow collector or custom event store. The library is actively maintained, with the current version being 1.1.0, and receives regular updates.

pip install snowplow-tracker

Common errors

error ModuleNotFoundError: No module named 'snowplow_tracker' ↓

cause The 'snowplow-tracker' library is not installed in the current Python environment, or the environment is not correctly activated.

fix

pip install snowplow-tracker

error TypeError: emitters must be a list of Emitter objects ↓

cause The `emitters` argument provided to the `Tracker` constructor was not a list containing `Emitter` instances.

fix

from snowplow_tracker import Emitter, Tracker emitter = Emitter('collector.example.com') tracker = Tracker([emitter])

error ValueError: Self-describing event payload must contain 'schema' and 'data' fields. ↓

cause A self-describing event or custom context dictionary was provided without the required 'schema' and 'data' keys, or they were malformed.

fix

event_json = {"schema": "iglu:com.example/my_event/jsonschema/1-0-0", "data": {"key": "value"}} tracker.track_self_describing_event(event_json)

error TypeError: tracker_name must be a string ↓

cause The `tracker_name` parameter during `Tracker` initialization was provided with a non-string value.

fix

from snowplow_tracker import Emitter, Tracker emitter = Emitter('collector.example.com') tracker = Tracker([emitter], tracker_name="my_application")

Warnings

gotcha When 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. ↓

fix Always provide a unique `namespace` argument when calling `Snowplow.create_tracker` or directly instantiating `Tracker`.

gotcha The 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. ↓

fix Ensure 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.

breaking The 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. ↓

fix Always 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.

breaking The `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. ↓

fix Review 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').

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.61s 21.8M

3.10 alpine (musl) - - 0.69s 21.8M

3.10 slim (glibc) wheel 2.1s 0.47s 22M

3.10 slim (glibc) - - 0.51s 22M

3.11 alpine (musl) wheel - 0.79s 24.0M

3.11 alpine (musl) - - 0.95s 23.9M

3.11 slim (glibc) wheel 2.2s 0.69s 24M

3.11 slim (glibc) - - 0.74s 24M

3.12 alpine (musl) wheel - 0.68s 15.7M

3.12 alpine (musl) - - 0.76s 15.7M

3.12 slim (glibc) wheel 2.0s 0.68s 16M

3.12 slim (glibc) - - 0.83s 16M

3.13 alpine (musl) wheel - 0.68s 15.5M

3.13 alpine (musl) - - 0.79s 15.3M

3.13 slim (glibc) wheel 2.0s 0.64s 16M

3.13 slim (glibc) - - 0.77s 16M

3.9 alpine (musl) wheel - 0.54s 21.1M

3.9 alpine (musl) - - 0.62s 21.1M

3.9 slim (glibc) wheel 2.5s 0.52s 22M

3.9 slim (glibc) - - 0.53s 22M

Imports

Snowplow
```
from snowplow_tracker import Snowplow
```
Preferred entry point for initializing a tracker with default emitter and subject settings.
Tracker
wrong
```
tracker = Tracker('collector.example.com')
```
correct
```
from snowplow_tracker import Tracker
```
While direct instantiation of Tracker, Emitter, and Subject is possible, Snowplow.create_tracker is recommended for most use cases as it simplifies initialization.
Emitter
wrong
```
emitter = Emitter('collector.example.com')
```
correct
```
from snowplow_tracker import Emitter
```
See note for Tracker; direct instantiation of components is an older pattern that is often replaced by `Snowplow.create_tracker`.
Subject
wrong
```
subject = Subject()
```
correct
```
from snowplow_tracker import Subject
```
See note for Tracker; direct instantiation of components is an older pattern that is often replaced by `Snowplow.create_tracker`.

Quickstart last tested: 2026-04-24

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). ")