Slack SDK (Python)

3.41.0 · active · verified Tue Mar 17

Official Slack SDK for Python. Current version is 3.41.0 (Mar 2026). PyPI package is 'slack-sdk', imports as 'slack_sdk'. The predecessor 'slackclient' is in maintenance mode — vast amounts of tutorial code still references it. This is the official replacement.

Warnings

breaking slackclient (pip install slackclient) is in maintenance mode. slack-sdk (pip install slack-sdk) is the official successor. They have different import paths: slack vs slack_sdk.
Fix: pip uninstall slackclient && pip install slack-sdk. Update imports from 'from slack import' to 'from slack_sdk import'.
breaking files.upload API is retired (Nov 12, 2025). New apps blocked from it since May 2024. Calling client.files_upload() on new apps returns method_deprecated error.
Fix: Use client.files_upload_v2() instead. Parameter change: channels= renamed to channel_id=, no longer accepts multiple channels or channel names.
breaking files_upload_v2 channel parameter is channel_id= (not channels= plural). Passing channels= silently fails or is ignored.
Fix: client.files_upload_v2(channel_id='C0123456789', file=filepath)
breaking aiohttp is no longer a required dependency in slack-sdk v3. AsyncWebClient and AsyncWebhookClient will raise ImportError if aiohttp is not explicitly installed.
Fix: Add aiohttp to requirements.txt explicitly when using async clients.
gotcha WebClient.run_async option removed in v3. Use AsyncWebClient for async operations instead of the v2 run_async=True flag.
Fix: Replace WebClient(token=..., run_async=True) with AsyncWebClient(token=...)
gotcha files_upload_v2 is asynchronous on the Slack server side. Even after a successful response, the file may not immediately appear in channel. Polling files.info or using Events API is required for post-upload processing.
Fix: Do not assume file is available in channel immediately after upload response.
gotcha Token type matters: Bot tokens (xoxb-) for most operations, User tokens (xoxp-) for user-scoped actions, App-level tokens (xapp-) for Socket Mode only. Mixing them causes invalid_auth or missing_scope errors.
Fix: Use xoxb- bot tokens for standard bot operations. xapp- tokens are only for Socket Mode handshake.

Install

pip install slack-sdk Python (current — official)
pip install slackclient Python (deprecated — do not use for new projects)

Imports

WebClient
```
from slack_sdk import WebClient
```
Package installs as slack-sdk but imports as slack_sdk. 'from slack import WebClient' is the old slackclient v2 pattern — raises AttributeError: module 'slack' has no attribute 'WebClient' if slack-sdk is installed instead.
SlackApiError
```
from slack_sdk.errors import SlackApiError
```
Same package rename issue. Error class moved to slack_sdk.errors in v3.

Quickstart

Minimal message post and file upload using slack-sdk v3.x.

import os
from slack_sdk import WebClient
from slack_sdk.errors import SlackApiError

client = WebClient(token=os.environ['SLACK_BOT_TOKEN'])

try:
    response = client.chat_postMessage(
        channel='#general',
        text='Hello world!'
    )
except SlackApiError as e:
    print(f"Error: {e.response['error']}")

# File upload (v2 — required for new apps)
client.files_upload_v2(
    channel='C0123456789',
    file='./report.pdf',
    filename='report.pdf'
)

view raw JSON →