import { Cards, Tabs, Callout } from 'nextra/components'

Mixpanel SDKs: Python

Getting Started

The Mixpanel Python library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device.

The Full API Reference, Library Source Code, and an Example Script is documented in our GitHub repo.

Installing the Library

You can get the library using pip.

# install the Mixpanel module
pip install mixpanel

Once the library is installed, import the Mixpanel object from the module, then initialize the object using your project token.

# import Mixpanel object from the module
from mixpanel import Mixpanel

# initialize Mixpanel
mp = Mixpanel("YOUR_PROJECT_TOKEN")

Library Configuration

The Mixpanel instance can be customized with different configurations using a custom consumer. Learn more about the consumer and the available parameters here.

Example Usage

# initialize Mixpanel
mp = mixpanel.Mixpanel(
  "YOUR_PROJECT_TOKEN",
  # use custom consumer where retry limit is set to 2
  consumer=mixpanel.Consumer(retry_limit=2),
)

Sending Events

Use track() to send an event by providing the distinct_id, event name, and any event properties. This will trigger a request to the /track API endpoint to ingest the event into your project.

The [/track endpoint](https://developer.mixpanel.com/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.

Example Usage

# import Mixpanel
from mixpanel import Mixpanel

# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# Track 'some_event' with "plan" event prop
# With distinct_id set to '12345'
mp.track('12345', 'some_event', {
    'plan': 'premium',
    'ip': 192.168.0.1
})

To track any geolocation data ($city, $region, mp_country_code), you will need to set the location property values in the event. Learn more about best practices for geolocation.

Importing Historical Events

The track() function is designed for real-time tracking in a server-side environment and will trigger request to the /track API endpoint, which will validate for events with a time stamp that is within the last 5 days of the request. Events older than 5 days will not be ingested.

Use the import_data() function to import events that occurred more than 5 days in the past. The import_data() function is based on the /import API endpoint.

Example Usage

# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# import event that is old
mp.import_data(
	api_key='', # deprecated but required
	distinct_id='sample_distinct_id', 
	event_name='some_event',
    timestamp=1634528073,
	properties = {'some_property': 'some value'},
	api_secret = 'project_api_secret' # used to authenticate request
	)

You can also use the mp-utils python module designed for scripting.

Managing User Identity

Since the Python SDK is a server-side library, IDs are not generated by the SDK. Instead, you will need to generate and manage the distinct_id yourself and include it in your events and profile data.

Learn more about server-side identity management.

Storing User Profiles

Create user profiles by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Python SDK provides a few functions for setting profile properties, which will trigger requests to the /engage API endpoint.

To track any geolocation data ($city, $region, $country_code) for profile updates, you will need to set the location property values. Learn more about best practices for geolocation.

Setting Profile Properties

Set profile properties on a user profile by calling the people_set() method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

Example Usage

# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# create a user profile with name and email props
mp.people_set('sample_distinct_id', {
    'name' : 'sam',
    '$email' : 'sam@example.com',
}, meta = {
    '$ignore_time' : True, # do not update $last_seen
    '$ip' : 0}) # do not update geolocation

# update name property with new value
mp.people_set('sample_distinct_id', {
    'name' : 'samantha'
}, meta = {'$ignore_time' : True,'$ip' : 192.168.0.1})

Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods here.

A few commonly used people methods are highlighted below:

<Tabs items={['people_set_once()','people_append()','people_union()','people_increment()']} > <Tabs.Tab> The people_set_once() method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set profile properties without the risk of overwriting existing data.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set profile properties for user "1234"
mp.people_set('1234', {
'name':'sam'
}, meta={'$ip':0})

# will be ignored since "name" already exists
mp.people_set_once('1234', {
'name':'samantha'
}, meta={'$ip':0})

# set "location" user prop since it does not exist
mp.people_set_once('1234', {
'location':'us'
}, meta={'$ip':0})
```

</Tabs.Tab> <Tabs.Tab> The people_append() method append values to a list profile property.

Use this method to add additional values to an existing list property instead of redefining the entire list.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set profile properties for user "1234"
mp.people_set('1234', {
    'name': 'sam',
    'roles': ['sales','engineer']
}, meta={'$ip':0})

# add "legal" to "roles"  
# new role values are ['sales','engineer','legal']
mp.people_append('1234', {
    'roles': 'legal'
}, meta={'$ip':0})

# .append() allows duplicates
# new "roles" values are ['sales','engineer','legal', 'legal']
mp.people_append('1234', {
    'roles': 'legal'
}, meta={'$ip':0})
```

</Tabs.Tab> <Tabs.Tab> The people_union() method append new values to a list property, excluding duplicates.

Use this method to create a list profile property that only contains unique values without duplicates.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set profile properties for user "1234"
mp.people_set('1234', {
    'name': 'sam',
    'roles': ['sales','engineer']
}, meta={'$ip':0})

# "engineer" ignored since it already exists
# append "legal" to "roles"
mp.people_union('1234', {
    'roles': ['engineer','legal']
}, meta={'$ip':0})
```

</Tabs.Tab> <Tabs.Tab> The people_increment() method increments a numeric property by a whole number.

Use this method to add to or subtract from your numeric property based on its current value.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set profile properties for user "1234"
mp.people_set('1234', {
    'name': 'sam',
    'age': 25
}, meta={'$ip':0})

# increment "age" by 2
mp.people_increment('1234', {'age':2})

# use negative number to decrement
# decrement "age" by 5
mp.people_increment('1234', {'age',-5});
```

</Tabs.Tab>

Group Analytics

Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the group_key and group_id.

group_key is the event property that connects event data to a group. (e.g. company)
group_id is the identifier for a specific group. (e.g. mixpanel,company_a,company_b, etc.)

Sending Group Identifiers With Events

All events must have the group key as an event property in order to be attributed to a group. Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the group_key as an event property with the group_id as the value.

Example Usage

mp = Mixpanel('YOUR_PROJECT_TOKEN')

# track "some_event" with a "distinct_id"
# event is attributed to the "mixpanel" company group
mp.track('sample_distinct_id', 'some_event', {
    'Plan Type' : 'Premium', 
    'company' : 'mixpanel'})

Multiple Groups

An event can be attributed to multiple groups by passing in the group_key value as a list of multiple group_id values.

Example Usage

mp = Mixpanel('YOUR_PROJECT_TOKEN')

# track "some_event" with a "distinct_id"
# event is attributed to 2 company groups: "mp-us" and "mp-eu"
mp.track('sample_distinct_id', 'some_event', {
    'Plan Type' : 'Premium', 
    'company' : ['mp-us','mp-eu']})

Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the group_key and group_id as a user profile property using the people_set() call.

Example Usage

# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set group key "company" as a user prop
# with group id "mixpanel" as value
mp.people_set('sample_distinct_id', {
    'name' : 'sam',
    'company' : 'mixpanel',
}, meta = {'$ignore_time' : True,'$ip' : 0})

Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee_count", and "subscription".

To set group profile properties, use the group_set() function, which will trigger a request to the /groups API endpoint.

Example Usage

mp = Mixpanel('YOUR_PROJECT_TOKEN')

# create group profile for the "mixpanel" company group
# set "Company Type" and "$name" group profile properties
mp.group_set('company', 'mixpanel', {
    'Company Type': 'Analytics',
     '$name': 'Mixpanel'})

Other Group Profile Methods

See all of the methods under the Group class here.

A few commonly used group methods are highlighted below:

<Tabs items={['group_set_once()','group_unset()','group_union()','group_remove()']}> <Tabs.Tab> The group_set_once() method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set group profile properties without the risk of overwriting existing data.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set group profile for "mixpanel" company group
mp.group_set('company','mixpanel', {
    'name': 'Mixpanel',
    'employee_count': 100
})

# ignored since "name" is already exists
mp.group_set_once('company','mixpanel', {
    'name': 'mp-us',
})

# set "location" group prop since it does not exist
mp.group_set_once('company','mixpanel', {
    'location': 'us',
})
```

</Tabs.Tab> <Tabs.Tab> The group_unset() method removes a group property from a group profile.

Use this method to delete unwanted group profile properties from a specific group profile.

**Example Usage**
```python 
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set group profile for the "mixpanel" company group
mp.group_set('company','mixpanel', {
    'name': 'Mixpanel',
    'employee_count': 100
})

# delete "employee_count" from the group profile
mp.group_unset('company','mixpanel', [
    'employee_count'
])

# only "name" remains as a group prop
```

</Tabs.Tab> <Tabs.Tab> The group_union() method append new values to a list property, excluding duplicates.

Use this method to create a list group profile property that only contains unique values without duplicates.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set group profile for the "mixpanel" company group
mp.group_set('company','mixpanel', {
    'name': 'Mixpanel',
    'features': ['reports','alerts','cohorts']
})

# add "data pipeline" to "features" prop
# ignore "alert" since it is a duplicate value
mp.group_union('company','mixpanel', {
    'features': ['data pipeline','alerts']
})
```

</Tabs.Tab> <Tabs.Tab> The group_remove() method removes a value from a list-valued group profile property.

Use this method to remove specific values from a list without affecting all of the other values in the list.

**Example Usage**
```python
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set group profile for the "mixpanel" company group
mp.group_set('company','mixpanel', {
    'name': 'Mixpanel',
    'features': ['reports','alerts','cohorts']
})

# remove "alerts" from "features"
# "features" now contain ["reports","cohorts"]
mixpanel.group_remove('company','mixpanel', {
    'features': ['alerts']
})
```

</Tabs.Tab>

Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Python SDK have a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

EU Data Residency

Route data to Mixpanel's EU servers by using a custom Consumer with an api_host set to the EU domain.

Example Usage

from mixpanel import Mixpanel

# use custom consumer with URLs set to Mixpanel's EU domain
mp_eu = Mixpanel(
  "YOUR_PROJECT_TOKEN",
  consumer=mixpanel.Consumer(api_host="api-eu.mixpanel.com"),
)

India Data Residency

Route data to Mixpanel's India servers by using a custom Consumer with an api_host set to the India domain.

Example Usage

from mixpanel import Mixpanel

# use custom consumer with URLs set to Mixpanel's India domain
mp_in = Mixpanel(
  "YOUR_PROJECT_TOKEN",
  consumer=mixpanel.Consumer(api_host="api-in.mixpanel.com"),
)

Geolocation

The Python SDK sets the request IP address to 0 for events and profiles, meaning by default you are not tracking geolocation properties, unless explicitly included in the event or profile update.

Release History

See all releases.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!