Installation

This guide covers all the ways to install TraceCraft and its optional dependencies.

Requirements

• Python 3.11 or later
• pip or uv package manager

Basic Installation

pip install tracecraft

uv add tracecraft

poetry add tracecraft

This installs the core TraceCraft SDK with:

• OpenTelemetry API and SDK
• Rich console output
• Pydantic models
• Basic exporters (Console, JSONL)

Optional Dependencies

TraceCraft uses optional dependencies for different features. Install only what you need:

Framework Integrations

pip install "tracecraft[langchain]"

pip install "tracecraft[llamaindex]"

pip install "tracecraft[pydantic-ai]"

pip install "tracecraft[claude-sdk]"

Export Targets

pip install "tracecraft[otlp]"

pip install "tracecraft[mlflow]"

pip install "tracecraft[tui]"

Auto-Instrumentation

pip install "tracecraft[auto]"

Automatically instruments popular LLM SDKs:

• OpenAI SDK (via opentelemetry-instrumentation-openai)
• Anthropic SDK (via opentelemetry-instrumentation-anthropic)

No code changes required - just import and initialize!

Cloud Platform Integrations

pip install "tracecraft[aws-agentcore]"

pip install "tracecraft[azure-foundry]"

pip install "tracecraft[gcp-vertex-agent]"

pip install "tracecraft[cloud]"

Convenience Bundles

TraceCraft provides convenience bundles for common use cases:

pip install "tracecraft[all]"

pip install "tracecraft[production]"

pip install "tracecraft[dev]"

Verification

Verify your installation:

import tracecraft
 
print(f"TraceCraft version: {tracecraft.__version__}")
 
# Test basic functionality
tracecraft.init()
print("TraceCraft initialized successfully!")

Development Installation

For contributing to TraceCraft:

# Clone the repository
git clone https://github.com/LocalAI/tracecraft.git
cd tracecraft
 
# Install with all extras using uv (recommended)
uv sync --all-extras
 
# Or using pip
pip install -e ".[all,dev]"
 
# Install pre-commit hooks
uv run pre-commit install
 
# Run tests
uv run pytest

Upgrading

To upgrade to the latest version:

pip install --upgrade tracecraft

uv pip install --upgrade tracecraft

poetry update tracecraft

Troubleshooting

Import Errors

If you see import errors for optional dependencies:

ModuleNotFoundError: No module named 'langchain_core'

Install the required extra:

pip install "tracecraft[langchain]"

Version Conflicts

If you encounter version conflicts with OpenTelemetry packages, ensure you’re using compatible versions:

pip install --upgrade opentelemetry-api opentelemetry-sdk

TraceCraft requires:

• opentelemetry-api >= 1.20
• opentelemetry-sdk >= 1.20

Platform-Specific Issues

macOS Apple Silicon

Some dependencies may require Rosetta 2 or native builds:

# Install Rosetta 2 if needed
softwareupdate --install-rosetta
 
# Or use native builds
pip install --no-binary :all: tracecraft

Windows

On Windows, you may need to install Visual C++ build tools for some dependencies:

Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

Next Steps

Now that TraceCraft is installed, follow the quick start guide:

Quick Start Guide