Skip to main content

RudderStack

RudderStack Python SDK

Ask DeepWiki

RudderStack’s Python SDK lets you track events from your Python application. Once enabled, the event requests hit the RudderStack servers. RudderStack then transforms and routes these events to your specified destination platforms.

More details on the Python SDK can be found in our documentation

Getting Started with Python SDK

Install rudder-sdk-python using pip:

pip install rudder-sdk-python

Initializing the RudderStack Client

import rudderstack.analytics as analytics

analytics.write_key = <SOURCE_WRITE_KEY>
analytics.on_error = <FAILURE CALLBACK>
analytics.debug = <True or False>
analytics.dataPlaneUrl = <RUDDERSTACK_DATA_PLANE_URL>

analytics.gzip = <True or False>

Sending Events

Once the RudderStack client is initialized, you can use it to send your customer events. A sample track call is shown below:

rudder_analytics.track('developer_user_id', 'Simple Track Event', {
  'key1': 'val1'
})
analytics.track('user_id', 'Simple Track Event', anonymous_id='anonymousId',
  properties={
  'key1': 'val1'
}, context={
  'key1': 'val1'
})

For more information on the supported calls, refer to the documentation.

Editing or dropping events before enqueue

Set before_enqueue to edit or drop events before they leave your process. It runs once per event, on the calling thread, after the SDK fills in messageId, timestamp, channel and context. It receives its own copy of the event as a dict. Return the (possibly edited) dict to send it, or None to drop it.

import rudderstack.analytics as analytics


def before_enqueue(msg):
    # Drop: internal test traffic never leaves the process
    if (msg.get('userId') or '').startswith('test-'):
        return None
    # Edit: strip the email before it is transmitted
    for container in (msg, msg.get('context')):
        if isinstance(container, dict):
            traits = container.get('traits')
            if isinstance(traits, dict):
                traits.pop('email', None)
    # Must return the event: an implicit None drops it
    return msg


analytics.before_enqueue = before_enqueue
# This hook redacts PII, so never fall back to the unredacted original
analytics.before_enqueue_on_error = 'drop'

Set module-level before_enqueue and before_enqueue_on_error before the first module call, when the default client is created. Later assignments do not reconfigure that client. Creating an explicit Client is the safe option when module calls may already have occurred:

from rudderstack.analytics.client import Client

client = Client(
    'YOUR_WRITE_KEY', before_enqueue=before_enqueue,
    before_enqueue_on_error='drop',
)
client.identify('user-id', traits={'email': 'ada@example.com', 'plan': 'pro'})
  • Returning None drops the event, including a hook that ends without a return. Client methods return (True, None) and on_error is not called.
  • With a hook configured, validation waits until the hook returns, so the hook can fix an invalid call. The returned dict uses the call's normal field and serialization validation. Events over Python's 4 MB limit raise the usual RuntimeError, just as without a hook; oversize is not a hook error.
  • If the hook raises an Exception, returns something other than a dict or None, or fails validation (including cyclic data), the SDK logs the error as thrown. The default before_enqueue_on_error='send' validates and sends the original event; 'drop' drops it. Hook errors never call on_error. If the original is also invalid under 'send', its validation error surfaces as it would without a hook.
  • channel and context.library are restored with one warning if changed. A changed messageId is kept; a missing or empty one is restored silently. Other fields, including type, are yours to change. IDs are not coerced again after the hook, and its result is not copied or cleaned.
  • The hook must be synchronous and thread-safe if you call the SDK from several threads. It runs once per event, including when delivery retries.
  • before_enqueue must be callable or None; before_enqueue_on_error must be 'send' or 'drop'. Invalid options fail at client construction.
  • sentAt is absent from the hook input; the SDK sets it on the batch when sending. Python enriches timestamp; it does not add Node's originalTimestamp or _metadata.
  • KeyboardInterrupt and SystemExit propagate.

Proxy configuration

Pass proxies when you create a Client. A Requests-style mapping is preferred:

from rudderstack.analytics.client import Client

client = Client(
    'SOURCE_WRITE_KEY',
    host='https://YOUR_DATA_PLANE_URL',
    proxies={
        'http': 'http://proxy.example:8080',
        'https': 'http://proxy.example:8080',
    },
)

A legacy string such as proxy.example:8080 is also supported. The SDK applies the string to both HTTP and HTTPS requests. If the string has no scheme, the SDK adds http://. An existing scheme is preserved.

Configured proxies are now used for event requests. Earlier versions ignored this option. Check that any existing proxy configuration is reachable before upgrading.

About RudderStack

RudderStack is a customer data platform for developers. Our tooling makes it easy to deploy pipelines that collect customer data from every app, website and SaaS platform, then activate it in your warehouse and business tools.

More information on RudderStack can be found here.

Contact Us

For more information on any of the sections covered in this readme, you can contact us or start a conversation on our Slack channel.

Metadata

Release files for rudder-sdk-python 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rudder-sdk-python 2.2.0
File Size Uploaded Provenance Actions
rudder_sdk_python-2.2.0.tar.gz 28.9 kB With provenance Details for rudder_sdk_python-2.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rudder-sdk-python 2.2.0
File Interpreter ABI Platform Actions
rudder_sdk_python-2.2.0-py2.py3-none-any.whl Python 2, Python 3 none any Details for rudder_sdk_python-2.2.0-py2.py3-none-any.whl

Total release size: 65.4 kB

Release files / rudder_sdk_python-2.2.0.tar.gz

Download URL rudder_sdk_python-2.2.0.tar.gz
Size 28.9 kB
Tags Source
SHA-256 checksum
How to use checksums
88ef79ca259c9f3e8450a50240ebac2889f73f570a9abdf22dae0c5c7cda7e25
BLAKE2b-256 checksum
How to use checksums
6dd8a9d6bd4c0e46aafbe4d6f91370295e6b52ff4bb0fba2d4b6870de3e6ce56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / rudder_sdk_python-2.2.0-py2.py3-none-any.whl

Download URL rudder_sdk_python-2.2.0-py2.py3-none-any.whl
Size 36.6 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
3f3705f0591ebdef6e0efd841ff796c37b3941c8ac53c7582559830646586c37
BLAKE2b-256 checksum
How to use checksums
6f1622ee8b34fecefb6e9ef572e824e05715f1e1796aff8c080ce3da8b607ffc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for rudder-sdk-python 2.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rudder_sdk_python-2.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page