slackblocks

Licence: MIT Licence: BSD-3-Clause Python Versions

Build Slack messages in Python — without writing JSON by hand.

slackblocks is a typed, validating Python wrapper around the Slack Block Kit API. It exists because Block Kit JSON is verbose, easy to get subtly wrong, and unpleasant to maintain in source control.

This release conforms to the shared cross-language slackblocks specification.

Why `slackblocks`?

Concise — SectionBlock("Hello, *world*!") instead of a 10-line JSON object.
Validated — character limits, required fields, mutually-exclusive options, and element-type restrictions are enforced at construction time, so you find out before hitting Slack's API.
Drop-in compatible with both the official slack-sdk and the legacy slackclient — unpack a Message directly into client.chat_postMessage(**message).
Typed — full type hints; ships py.typed.
Zero runtime dependencies.

Installation

pip install slackblocks

slackblocks 2.x requires Python 3.10 or newer. Users on Python 3.8 / 3.9 should pin to the 1.x line — see the Compatibility page.

Quickstart

from slackblocks import (
    ActionsBlock,
    Button,
    DividerBlock,
    HeaderBlock,
    Message,
    SectionBlock,
)

message = Message(
    channel="#general",
    text="Build #482 passed",  # plain-text fallback for notifications
    blocks=[
        HeaderBlock("Build #482 passed :white_check_mark:"),
        SectionBlock(
            fields=[
                "*Branch*\n`main`",
                "*Author*\n@nick",
                "*Duration*\n3m 12s",
                "*Tests*\n1,247 passed",
            ],
        ),
        DividerBlock(),
        ActionsBlock(
            elements=[
                Button(text="View build", action_id="view", url="https://ci.example.com/482"),
                Button(text="Re-run", action_id="rerun", value="482", style="primary"),
            ],
        ),
    ],
)

message can be sent in one line with the official Slack SDK:

import os
from slack_sdk import WebClient

client = WebClient(token=os.environ["SLACK_API_TOKEN"])
client.chat_postMessage(**message)

The ** operator unpacks slackblocks Message objects directly into the SDK call — no to_dict() boilerplate required.

A simple Slack message rendered in Slack

What's supported

Surface	Status
Blocks	✅ All current block types, including Alert, Card, Carousel, Container, Context Actions, Data Table, Data Visualization, Plan, and Task Card
Elements	✅ Buttons, all select menus, date/time pickers, checkboxes, radio groups, all input types, overflow menus, workflow buttons
Composition Objects	✅ Text (+ `PlainText` / `Markdown` aliases), Option, Confirm, Conversation/Dispatch filters, Workflow, Trigger
Rich Text	✅ Sections, lists, quotes, code blocks, inline links/users/channels/emoji
Modals & Home Tabs	✅ Full views API
Messages	✅ `chat.postMessage`, webhook messages, slash-command/interaction responses, threaded replies, ephemeral messages
Attachments	⚠️ Supported but deprecated by Slack
Round-tripping	✅ `Block.from_dict(data)` and per-class `from_dict` for parsing incoming Slack JSON back into objects

What's new in 2.0

slackblocks 2.x is the first major release in the modernised line. Highlights:

Two new block types: MarkdownBlock (GitHub-flavored Markdown) and VideoBlock.
PlainText and Markdown thin aliases for Text(type_=...).
block_kit_builder_url(payload) — turn any block, message, or view into a Block Kit Builder URL for browser preview.
Workflow.from_url(url, **params) — one-line workflow construction.
Block.from_dict(data) + per-class from_dict parsers — round-trip incoming Slack JSON back into slackblocks objects.
Typed exception subclasses of InvalidUsageError (LengthError, RangeError, TypeMismatchError, MutualExclusivityError, MissingRequiredError) — existing except InvalidUsageError blocks continue to work.
Tighter type signatures: Literal narrowing on Button.style, ColumnSettings.align, ConversationFilter.include; @overload on Text.to_text so the return type narrows on allow_none.
Modern annotation syntax (list[X], X | Y) throughout.

Existing 1.x code continues to work unchanged; see the Migration Guide for the full diff.

Documentation

Full docs: https://nicklambourne.github.io/slackblocks/
Installation
Compatibility — which Python versions each release line supports.
Using Blocks — every block type with code, JSON, and screenshots.
Sending Messages
Cookbook — end-to-end recipes for build notifications, approval requests, modals, and more.
Migrating from 1.x — upgrade guide for 1.x users.
Troubleshooting & FAQ
Changelog

Comparison with `slack-sdk` block classes

The official slack-sdk ships its own block classes. slackblocks predates them and offers a more concise API, stricter up-front validation, and independent versioning. They produce equivalent JSON; pick whichever you find more ergonomic.

# slackblocks
SectionBlock("Hello, *world*!")

# slack-sdk equivalent
from slack_sdk.models.blocks import SectionBlock as SDKSectionBlock
from slack_sdk.models.blocks.basic_components import MarkdownTextObject
SDKSectionBlock(text=MarkdownTextObject(text="Hello, *world*!"))

Licensing

slackblocks is dual-licensed under MIT and BSD-3-Clause. Use whichever fits your project — this makes it safe to vendor into projects under either license.

Contributing

Contributions are welcome. Quick start (the project uses uv for dependency management):

git clone https://github.com/nicklambourne/slackblocks.git
cd slackblocks/python
uv sync --all-groups

uv run pytest test/unit test/conformance test/docs
uv run ruff format --check slackblocks test
uv run ruff check slackblocks test
uv run mypy slackblocks

Preview the documentation from the repository root with pnpm --filter @slackblocks/docs start.

For the full development guide — testing conventions, validation patterns, docstring style, release process, and a PR checklist — see the Contributing page.

Bug reports and feature requests: https://github.com/nicklambourne/slackblocks/issues.

Metadata

Release files for slackblocks 2.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for slackblocks 2.5.0
File	Size	Uploaded
slackblocks-2.5.0.tar.gz	196.8 kB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for slackblocks 2.5.0
File	Interpreter	ABI	Platform	Reset
slackblocks-2.5.0-py3-none-any.whl 63.9 kB Sep 28, 2026	Python 3	none	any	Details

Total release size: 260.7 kB

Release files / slackblocks-2.5.0.tar.gz

Download URL	slackblocks-2.5.0.tar.gz
Size	196.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`65df8ec8df4ec2599ef3f4a6516641d5621c727498623110a77ec4fc380a027a`
BLAKE2b-256 checksum How to use checksums	`6f7a41d630149abb172fb28b6f9b2a06cd6ff2434f124c9b5d653eec33229894`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / slackblocks-2.5.0-py3-none-any.whl

Download URL	slackblocks-2.5.0-py3-none-any.whl
Size	63.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f2f495aed2750af7e62c9f03ca2fd0d8b131deb3a3eac7a3ee15bcac1e0cdf91`
BLAKE2b-256 checksum How to use checksums	`7467c16f2a3042521e1ba40ed62fa9f1b08e3b0e91975470f578ba1a09611bc9`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`