Facebook SDK for Python

3.1.0 · active · verified Wed Apr 15

This client library is designed to support the Facebook Graph API, providing a Python interface to interact with Facebook's social graph objects like users, posts, pages, and events. It also supports the official Facebook JavaScript SDK for authentication. The current stable version is 3.1.0, released in November 2018. While this project is maintained, users dealing with Meta Business (Marketing) APIs should consider the 'facebook-python-business-sdk' which is more actively developed for those specific use cases.

Warnings

breaking Version 3.0.0 introduced significant breaking changes. It removed support for Python 2.6 and 3.3, and older Graph API versions (2.1-2.6). The `put_wall_post` method was removed; use `put_object` instead.
Fix: Upgrade Python to 3.5+ (Python 2.7 support is removed in v4.0.0-pre). Update Graph API calls to supported versions. Replace `put_wall_post` with `put_object`.
gotcha Facebook's Graph API undergoes frequent version changes and deprecations. Always specify the `version` parameter when initializing `facebook.GraphAPI` to avoid unexpected behavior or API calls defaulting to an unsupported or deprecated version. For instance, `facebook-sdk` v3.1.0 defaulted to Graph API v2.7, which is now very old.
Fix: Initialize `GraphAPI` with `version='x.y'` (e.g., `GraphAPI(ACCESS_TOKEN, version='2.12')`). Regularly check Meta's Graph API changelog for updates.
gotcha Access tokens are central to authentication and have varying expiration times and required permissions. Using expired tokens or lacking necessary permissions will result in `GraphAPIError` exceptions. User `user_friends` permission will only return friends who have also authorized your app.
Fix: Ensure your access token is valid and unexpired. Obtain the correct permissions for the data you are trying to access. Handle `GraphAPIError` exceptions for authentication and permission issues gracefully. Use long-lived access tokens where appropriate.
deprecated For applications interacting with Meta's Business (e.g., Marketing, Ads, Pages, Business Manager, Instagram) APIs, the official and actively developed SDK is `facebook-python-business-sdk` (PyPI package `facebook_business`). The `facebook-sdk` library is primarily for general Graph API access and may not include the latest features or optimal support for business-specific functionalities.
Fix: If your application targets business-related functionalities, migrate to `facebook-python-business-sdk` and its `facebook_business` module. Note that this is a separate library with different import paths and usage patterns.
breaking The upcoming version 4.0.0 (currently in pre-release) explicitly removes support for Python 2.7 and 3.4. It also removes support for Graph API versions 2.8, 2.9, 2.10, 2.11, 2.12, and 3.0, updating default Graph API version to 2.10.
Fix: Ensure your environment uses Python 3.5+ (preferably 3.8+ for 4.0.0-pre) and update your Graph API version parameter to a supported version for the 4.x series.

Install

pip install facebook-sdk Install stable version

Imports

GraphAPI
```
import facebook
graph = facebook.GraphAPI(...)
```
The primary class for interacting with the Facebook Graph API.

Quickstart

This quickstart demonstrates how to initialize the `GraphAPI` client and fetch basic user profile information. You need an access token, which can be obtained from the Facebook Developer Tools. Remember to grant appropriate permissions for the data you wish to access. Always specify the Graph API version.

import os
import facebook

# It is highly recommended to use environment variables for sensitive data like tokens
ACCESS_TOKEN = os.environ.get('FB_ACCESS_TOKEN', 'YOUR_ACCESS_TOKEN_HERE')

if not ACCESS_TOKEN or ACCESS_TOKEN == 'YOUR_ACCESS_TOKEN_HERE':
    print("Please set the FB_ACCESS_TOKEN environment variable or replace 'YOUR_ACCESS_TOKEN_HERE' with your actual access token.")
else:
    try:
        # Initialize the Graph API with your access token
        # Specify the API version for forward compatibility
        graph = facebook.GraphAPI(ACCESS_TOKEN, version="2.12") # Use a specific version, e.g., "2.12" or higher

        # Get information about the current user ('me')
        profile = graph.get_object('me', fields='id,name,email')
        print(f"Hello, {profile['name']}! Your ID is {profile['id']} and email is {profile.get('email', 'not provided')}.")

        # Example: Get a list of friends (requires 'user_friends' permission)
        # Note: This will only return friends who have also used the app.
        # friends = graph.get_connections('me', 'friends')
        # print("Your friends who use this app:")
        # for friend in friends['data']:
        #     print(f"- {friend['name']} (ID: {friend['id']})")

    except facebook.GraphAPIError as e:
        print(f"Facebook Graph API Error: {e.type} - {e.message}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →