> ## Documentation Index
> Fetch the complete documentation index at: https://mixpanel-edb78807-tylergoerzen-tof-687-regional-hosts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](http://mixpanel.github.io/mixpanel-python), [Library Source Code](https://github.com/mixpanel/mixpanel-python), and an [Example Script](https://github.com/mixpanel/mixpanel-python/tree/master/demo) is documented in our GitHub repo.

## Installing the Library

You can get the library using [pip](https://pypi.org/project/pip/).

```shell theme={null}
# 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](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```py theme={null}
# import Mixpanel object from the module
from mixpanel import Mixpanel

# initialize Mixpanel
mp = Mixpanel("YOUR_PROJECT_TOKEN")
```

### Library Configuration

<Warning>
  Mixpanel supports [EU](/docs/privacy/eu-residency) and [India](/docs/privacy/in-residency) data residency, which you choose per project. If your project uses either, pass a `Consumer` with `api_host` set to `api-eu.mixpanel.com` or `api-in.mixpanel.com`. Events sent to the wrong region aren't ingested. See [EU Data Residency](#eu-data-residency) and [India Data Residency](#india-data-residency) for examples.
</Warning>

The Mixpanel instance can be customized with different configurations using a custom `consumer`. Learn more about the consumer and the available parameters [here](https://mixpanel.github.io/mixpanel-python/#built-in-consumers).

**Example Usage**

```py theme={null}
# 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()`](http://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/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.
</Note>

**Example Usage**

```python theme={null}
# 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.](/docs/tracking-best-practices/geolocation)

### Importing Historical Events

The [`track()`](http://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.track) function is designed for real-time tracking in a server-side environment and will trigger request to the [/track API endpoint](/reference/track-event), 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()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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](/reference/import-events).

**Example Usage**

```py theme={null}
# 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](https://github.com/mixpanel/mixpanel-utils) 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](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

## Storing User Profiles

Create [user profiles](/docs/data-structure/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](/reference/profile-set).

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.](/docs/tracking-best-practices/geolocation)

### Setting Profile Properties

Set profile properties on a user profile by calling the [`people_set()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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**

```python theme={null}
# 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](https://mixpanel.github.io/mixpanel-python).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="people_set_once()">
    The [`people_set_once()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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})
    ```
  </Tab>

  <Tab title="people_append()">
    The [`people_append()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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})
    ```
  </Tab>

  <Tab title="people_union()">
    The [`people_union()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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})
    ```
  </Tab>

  <Tab title="people_increment()">
    The [`people_increment()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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});
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  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.
</Note>

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](/docs/data-structure/group-analytics/group-analytics-implementation#tracking-events-for-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**

```python theme={null}
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](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```python theme={null}
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**

```python theme={null}
# 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()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_set) function, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```py Python theme={null}
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](https://mixpanel.github.io/mixpanel-python/).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="group_set_once()">
    The [`group_set_once()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_set) 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 theme={null}
    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',
    })
    ```
  </Tab>

  <Tab title="group_unset()">
    The [`group_unset()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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
    ```
  </Tab>

  <Tab title="group_union()">
    The [`group_union()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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']
    })
    ```
  </Tab>

  <Tab title="group_remove()">
    The [`group_remove()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.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 theme={null}
    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']
    })
    ```
  </Tab>
</Tabs>

## 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**

```py theme={null}
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**

```py theme={null}
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.](https://github.com/mixpanel/mixpanel-python/releases)