Implementation:Bigscience workshop Petals Petals Installation

Knowledge Sources	Petals
Domains	Infrastructure, Setup
Last Updated	2026-02-09 14:00 GMT

Overview

Concrete tool for installing the Petals package and configuring HuggingFace authentication, provided via pip and the HuggingFace CLI.

Description

Petals is installed via pip from PyPI. The pyproject.toml defines the package with its dependencies. Installation pulls in all required libraries for distributed model inference.

Package structure (from pyproject.toml):

• Name: petals
• Python requirement: >=3.8
• Key dependencies: hivemind, transformers, torch, accelerate, safetensors, dijkstar, cpufeature, huggingface-hub

HuggingFace authentication: Required for gated models. Can be configured via:

• huggingface-cli login (interactive)
• HF_TOKEN environment variable
• token= parameter in from_pretrained() calls

Usage

Run pip install petals for client usage. For server deployment, Docker images are recommended. For training workflows, additionally install datasets and wandb.

Code Reference

Source Location

• Repository: petals
• File: pyproject.toml (L1-18)
• File: src/petals/__init__.py (L1-35, dependency version checks)

Signature

# Client installation
pip install petals

# With training dependencies
pip install petals datasets wandb

# HuggingFace authentication
huggingface-cli login

Import

# Verify installation
import petals
from petals import AutoDistributedModelForCausalLM

I/O Contract

Inputs

Name	Type	Required	Description
Python environment	>= 3.8	Yes	Python interpreter with pip
CUDA drivers	CUDA 11.x+	No	Required for GPU server contribution
HuggingFace token	str	No	Required only for gated models (e.g., Llama 2)

Outputs

Name	Type	Description
petals package	Python package	Installed with all dependencies
HF authentication	Session state	Authenticated HuggingFace CLI (if login performed)

Usage Examples

Client Setup

# Install Petals
pip install petals

# Verify
python -c "from petals import AutoDistributedModelForCausalLM; print('OK')"

Server Setup with Docker

# Pull and run the official Docker image
docker run -p 31330:31330 --ipc host --gpus all \
    --volume petals-cache:/cache --rm \
    learningathome/petals:main \
    python -m petals.cli.run_server petals-team/StableBeluga2

Training Workflow Setup

# Install with training extras
pip install petals datasets wandb

# Login to HuggingFace for gated models
huggingface-cli login

# Login to Weights & Biases for experiment tracking
wandb login

Related Pages

Implements Principle

• Principle:Bigscience_workshop_Petals_Environment_Setup