Installation

Install specklepy and set up your Python environment

Requirements

specklepy requires:

• Python 3.10 or higher (Python 3.10, 3.11, 3.12, 3.13, 3.14 supported)

specklepy works on Windows, macOS, and Linux.

Install with pip

You can install specklepy using pip in the current environment:

pip install specklepy

Install a Specific Version

To install a specific version:

pip install specklepy==3.0.10

Upgrade to Latest Version

To upgrade an existing installation:

pip install --upgrade specklepy

Virtual Environments (Recommended)

It’s best practice to use a virtual environment to avoid dependency conflicts.

uv (Recommended)

# Install uv if you don't have it
pip install uv

# Create a new project with virtual environment
uv init my-speckle-project
cd my-speckle-project

# Add specklepy
uv add specklepy

# Run your script
uv run python main.py

UV is blazingly fast and the preferred tool by the Speckle team!

venv (Built-in)

# Create virtual environment
python -m venv speckle_env

# Activate it
# On Windows:
speckle_env\Scripts\activate
# On macOS/Linux:
source speckle_env/bin/activate

# Install specklepy
pip install specklepy

conda

# Create conda environment
conda create -n speckle_env python=3.11

# Activate it
conda activate speckle_env

# Install specklepy
pip install specklepy

Verify Installation

Confirm specklepy is installed correctly:

import specklepy
print(f"specklepy version: {specklepy.__version__}")

You can also check available modules:

from specklepy.api.client import SpeckleClient
from specklepy.objects.geometry import Point
from specklepy.api import operations

print("✓ specklepy installed successfully!")

Dependencies

specklepy automatically installs these dependencies:

Package	Purpose
gql[requests,websockets]	GraphQL client for Speckle Server API
pydantic	Data validation and serialization
appdirs	Cross-platform directory paths
stringcase	String case conversion
ujson	Fast JSON parsing
deprecated	Deprecation warnings

You don’t need to install these manually - pip handles them automatically.

Development Installation

If you want to contribute to specklepy or modify the source code refer to the contributing guide.

Next Steps

Now that you have specklepy installed, learn how to authenticate:

Authentication

Set up authentication with Speckle Server