specklepy

The Python SDK for Speckle - Build powerful AEC data workflows

specklepy is the Python SDK for Speckle, enabling you to interact with Speckle Server, send and receive geometry, and build custom integrations for the AEC industry.

New to Speckle SDKs? Start with the shared SDK introduction for platform concepts and how Python and .NET relate.

GitHub Repository

Compatible with Speckle Object Model v3

Quick Start

Get up and running in 5 minutes

Core Concepts

Understand the fundamentals

API Reference

Explore the complete API

📚 Complete API Documentation: For detailed, auto-generated API reference documentation, visit the specklepy API Documentation.

What is specklepy?

specklepy is a comprehensive Python library that provides:

• Object-based data exchange - Send and receive geometry and BIM data without files
• GraphQL API client - Full access to Speckle Server’s API
• Extensible object model - Create custom objects that inherit from Base
• Multiple transport options - Store data locally (SQLite), in-memory, or on Speckle Server
• Geometry support - Rich geometric primitives (Point, Line, Mesh, Brep, etc.)
• Structural analysis - Complete FEA/FEM object types

specklepy v3 requires Python 3.10+ and supports Windows, macOS, and Linux.

Key Features

Object-Based, Not File-Based

Forget about files. Speckle uses objects as the fundamental unit of data exchange.

# Create geometry objects
start = Point(x=0, y=0, z=0)
end = Point(x=10, y=10, z=0)
line = Line(start=start, end=end)

Instead of files, Speckle stores sets of objects in Models. Models are contained within Projects. Projects are contained within Workspaces. Learn more about organising your data in Speckle in the User Guide.

Version Control for AEC Data

Every change creates a new version (commit), giving you full history and traceability.

# Create a version with your data
version_input = CreateVersionInput(
    project_id=project_id,
    model_id=model_id,
    object_id=object_id,
    message="Updated geometry"
)
version = client.version.create(version_input)

The object_id here is of a Speckle object that has already been sent to the Speckle server. Sending will register it in the database, but visibility of it is within the scope of a version.

Objects not associated with a Model Version are considered as “Zombie objects” or “Orphans” other than keeping a record of object_ids they will be irretrievable.

Real-Time Collaboration

Subscribe to changes and get notified when new data arrives.

# Subscribe to project updates
client.subscribe.project_versions_updated(
    project_id=project_id,
    callback=on_version_created
)

Subscriptions may not make sense if the script is not running continuously. Consider using a webhook or a scheduled task instead.

Common Use Cases

Custom Python backed web applications

Extract data from one application (e.g., Revit) and load it into another that may have a python scripting interface and no Speckle Connector.

Automated Workflows

Within Speckle Automation or your own automation pipelines that process AEC data, run analyses, or generate reports.

Custom Integrations

Connect Speckle to your internal tools, databases, applications with a python scripting environment, or third-party services.

Structural Analysis

Work with FEA/FEM models using the built-in structural object types.

Installation

Install specklepy using pip:

pip install specklepy

For detailed installation instructions, see the Installation Guide.

Quick Example

Here’s a complete example of sending geometry to Speckle:

from specklepy.api.client import SpeckleClient
from specklepy.api.credentials import get_default_account
from specklepy.api import operations
from specklepy.objects.geometry import Point
from specklepy.transports.server import ServerTransport
from specklepy.core.api.inputs.version_inputs import CreateVersionInput

# Authenticate
client = SpeckleClient(host="https://app.speckle.systems")
account = get_default_account()
client.authenticate_with_account(account)

# Create geometry
point = Point(x=10, y=20, z=5)

# Send to server
transport = ServerTransport(stream_id="your_project_id", client=client)
object_id = operations.send(base=point, transports=[transport])

# Get the main model
models = client.model.get_models("your_project_id")
model_id = models.items[0].id

# Create a version
version_input = CreateVersionInput(
    project_id="your_project_id",
    model_id=model_id,
    object_id=object_id,
    message="My first point!"
)
version = client.version.create(version_input)

print(f"Created version: {version.id}")

Next Steps

Installation

Install specklepy and set up your environment

Authentication

Learn how to authenticate with Speckle Server

Quickstart

Build your first integration

Core Concepts

Understand how specklepy works

Getting Help

Community Forum

Ask questions and share knowledge

GitHub Issues

Report bugs and request features