Slack's Python SDK: nine modules, one token, and a v3 migration

Nine modules, one package, nine different Slack surfaces

The design decision that explains this SDK is stated early: the Slack platform offers several APIs to build apps, each API delivers part of the platform's capabilities, and this SDK offers a corresponding package for each one. What you get is a directory of small clients rather than one God object.

The list in the README is the clearest map of the package:

- `slack_sdk.web` calls the Web API methods, which is the bulk of what most integrations use - `slack_sdk.webhook` handles incoming webhooks and the `response_url` values that appear in interactive payloads - `slack_sdk.signature` verifies that an incoming request genuinely came from Slack - `slack_sdk.socket_mode` receives and sends messages over Socket Mode connections - `slack_sdk.audit_logs` reaches the admin Audit Logs API - `slack_sdk.scim` covers SCIM, which is how enterprise directory provisioning works - `slack_sdk.oauth` implements the Slack OAuth install flow - `slack_sdk.models` builds Block Kit UI components - `slack_sdk.rtm` talks to the older RTM API

Read that list as a dependency graph. `oauth` produces the token. `web` spends it. `signature` protects what you do with tokens you did not mint. `socket_mode` is what makes a bot responsive without a public HTTP endpoint. `models` is a convenience layer over JSON payloads that you could otherwise build by hand.

The separation has a practical payoff. If you only send notifications, you depend on `web` and nothing else, and you can treat the rest of the package as unused. If you are building an interactive app, you probably want `web`, `models`, `signature` and `socket_mode` together.

One thing the SDK deliberately does not do is cover the Events API and interactivity at a high level. The README points those users to Bolt for Python instead. So the boundary is: this SDK gives you the transport and the payload shapes, and Bolt gives you the listener and dispatch machinery on top.

Two commands to install, one to verify

Installation is a single PyPI install, and the README recommends PyPI explicitly:

$ pip install slack_sdk

Note the package name is `slack_sdk` with an underscore, not `slack-sdk` and not `slack`. That detail saves people an afternoon when a dependency resolver reports a missing module.

The README also spends a paragraph on the prerequisite rather than assuming it. The library requires Python 3.7 and above, and the check is:

python --version

-- or --

python3 --version

The note attached to that block matters more than the command: you may need `python3` in front of your commands to get the right interpreter, so a bare `python` on your machine is not evidence that your project runs on 3.7 or better.

That 3.7 floor is older than you might expect for a package with this release cadence. The current release series is v3, with v3.44.1 published on 2026-09-03, v3.44.0 on 2026-08-27 and v3.43.0 on 2026-06-30. The main branch was pushed on 2026-09-10, so development is current rather than abandoned, and the 3.7 declaration in `pyproject.toml` is a deliberate floor rather than neglect. Treat it as a promise that the package will not drop you, not as a sign that the package is stale.

The WebClient pattern and why errors are objects

The canonical example is short enough to memorise, and every part of it teaches something about the design:

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='#random', text="Hello world!")

Three choices here are worth copying into your own code.

The token comes from an environment variable, not a literal. `WebClient` takes a token at construction time and holds it, so the object you pass around your application does not carry the secret in each call site.

The channel is written as `#random`, and the README immediately advises against that. It recommends using the `channel_id` where possible, because channel names can be renamed by users while IDs cannot. It also flags a permission detail that trips up first-time app builders: if your bot user is not already in a channel, invite it before running the snippet, or add the `chat:write.public` bot token scope so it can post in any public channel.

Then there is the error type. `SlackApiError` is raised when the platform response reports `ok` as false, and the handler reaches into `e.response`. The response carries the platform's own error string, values like `invalid_auth` or `channel_not_found`, and it also carries an HTTP status code. That means a missing scope, an expired token and a bad channel name are three distinguishable conditions in your retry and alerting logic, rather than one exception type. For a package that wraps an HTTP API, this is the single most useful thing it does.

Async usage for scripts and for frameworks

The README's table of contents points at an async usage section covering two cases: a `WebClient` used as a script, and a `WebClient` inside a framework. The distinction matters because the underlying transport supports both aiohttp and a websocket client, which is also what the repository topics list, alongside asyncio and socket mode.

For a script, the async client lets you fire many Slack calls concurrently without spawning threads. Slack's Web API is rate limited per method per workspace, so the common script that posts to forty channels is exactly the shape of work where serial requests become the bottleneck.

For a framework, you get the client as an async resource that fits an application's startup and shutdown lifecycle, which is what you need for `socket_mode`, where a single long-lived connection must survive as long as the process does.

The advanced options section is worth knowing about because these are the failures that show up in production rather than in the tutorial. It covers SSL configuration, proxy support, DNS performance and an example of combining them. DNS performance in particular is not a detail you would think about if the library were synchronous and used once, but a socket mode connection re-resolves names on reconnect, and a slow resolver shows up as reconnect churn.

The migration guide is linked separately from the v1 discussion, and it is the one reference you should treat as mandatory if you inherit older code.

Why slackclient is in maintenance mode

The README contains a short section titled slackclient is in maintenance mode, and it exists because the PyPI name most people search for is not the package you want. The `slackclient` project is in maintenance mode, and `slack_sdk` is its successor. If you have time, the README asks you to follow the v3 migration guide to make sure your app keeps working after updating.

That distinction is visible in the repository tree, which carries both a `slack/` directory and a `slack_sdk/` directory, and in `pyproject.toml`, where the package discovery rule includes both `slack*` and `slack_sdk*` globs. The v1 namespace is still shipped, which means a codebase can easily end up importing from both.

The practical failure mode here is not a crash. It is a dependency that resolves to the maintained package while your code imports the deprecated one, or a vendored copy of the old namespace that quietly stops receiving fixes. The cheapest defence is a single grep for `from slack.` and `import slack.` in your service, because anything matching should be on your migration list.

The version boundary is explicit in the README: migrate to `slack_sdk` v3. Treat v1 as an end state you are leaving, not a version you can defer indefinitely while the API keeps moving.

What the repository signals about maintenance

The top-level tree tells you what kind of project this is. Beyond the package directory and tests, there is an `AGENTS.md` at the root, a `.claude/` directory, a `tutorial/` directory, an `integration_tests/` directory, a `docs/` directory, a `logs/` directory and a `scripts/` directory.

An `AGENTS.md` file and a `.claude/` directory mean the project has opted into machine-readable contribution instructions, which is a signal about how the maintainers expect changes to be proposed. The presence of `integration_tests` next to `tests` means there is a split between unit coverage and live-workspace coverage, which for an API client is the honest split, since most of the interesting failures happen against the real platform.

The `tutorial/` directory is the answer to the getting started question, and the README describes it as building a basic Slack app in less than ten minutes, covering the Web API and the RTM API, aimed at developers with general programming knowledge and Python basics.

The packaging metadata is more opinionated than most. `pyproject.toml` requires Python 3.7 or above, runs on both CPython and PyPy, lists classifiers through Python 3.14, and sets ruff to a 125-character line length with E, W, F and D rule sets selected and docstring rules partly ignored. The package is MIT licensed, and the description it gives itself is the Slack API Platform SDK for Python, classified as Production/Stable.

For an adopter the practical takeaway is about cadence rather than structure. Three releases between June and September 2026, a push on 2026-09-10 and a Production/Stable classifier together mean you are depending on something maintained, and the cost of that maintenance is your obligation to follow the v3 migration when it lands.

Editorial conclusion

This SDK is the right dependency for any Python service that talks to Slack, because the modules are thin wrappers you can read in an afternoon and the error objects carry the platform error code rather than a generic failure. Two things deserve attention before you commit: the package still declares Python 3.7 as its floor, and the v1 to v3 migration is real work rather than a version bump. Start with `slack_sdk.web.WebClient` against a single channel, then add `slack_sdk.socket_mode` only once you have verified token scopes, and read the migration guide before you inherit any code that still imports from the `slack` namespace.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. slackapi/python-slack-sdk on GitHub