Installation¶

This guide walks you through installing PaperTrail and its dependencies.

System Requirements¶

Python: 3.9 or later
OS: Linux, macOS, or Windows
Slack: Access to a Slack workspace with API permissions

Installation Methods¶

Option 1: Install with Pip (Recommended)¶

Install from PyPI with your preferred embedding backend:

OpenAI (recommended)HuggingFace Inference APILocal ONNX modelsAll backendsMinimal (no embeddings)

pip install papertrail-lab[openai]

Includes everything needed for OpenAI embeddings via text-embedding-3-small.

pip install papertrail-lab[huggingface]

Uses HuggingFace Inference API with BAAI/bge-small-en-v1.5 model.

pip install papertrail-lab[local]

Uses local fastembed with no API keys required.

pip install papertrail-lab[all]

Installs all embedding backends so you can switch between them.

pip install papertrail-lab

Installs only core dependencies. You'll need to add an embedding backend separately.

Option 2: Install from Source¶

For development or latest features:

git clone https://github.com/bschilder/PaperTrail.git
cd PaperTrail
pip install -e ".[dev]"

The -e flag installs in editable mode, so changes to the code are immediately reflected.

Verify Installation¶

Check that PaperTrail is installed correctly:

papertrail --version

You should see the version number (e.g., PaperTrail version 0.1.0).

Next Steps¶

Configure Your Environment — Set up API tokens and credentials
Quick Start — Run the pipeline for the first time
Troubleshooting — Resolve common installation issues

Troubleshooting¶

Error: `pip: command not found`¶

Python and pip may not be installed or not in your PATH. Install Python from python.org or use a package manager:

macOSUbuntu/DebianWindows

brew install python3

sudo apt-get install python3 python3-pip

Download and run the Python installer from python.org.

Error: `ModuleNotFoundError: No module named 'papertrail'`¶

The package wasn't installed correctly. Try reinstalling:

pip install --upgrade --force-reinstall papertrail-lab

If you're using a virtual environment, make sure it's activated:

# Create a virtual environment
python3 -m venv papertrail-env

# Activate it
source papertrail-env/bin/activate  # macOS/Linux
# or
papertrail-env\Scripts\activate  # Windows

# Then install
pip install papertrail-lab[all]

Error: `No module named 'slack_sdk'` or `openai`¶

You installed the minimal package without a backend. Install a backend:

pip install papertrail-lab[openai]  # or [huggingface] or [local]

Error: `ImportError` with embedding libraries¶

Make sure you installed the correct backend extras:

# For OpenAI
pip install papertrail-lab[openai]

# For HuggingFace
pip install papertrail-lab[huggingface]

# For local models
pip install papertrail-lab[local]

Windows Users: Long Path Errors¶

If you encounter path length errors on Windows, enable long paths:

# Run PowerShell as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Platform-Specific Notes¶

macOS¶

If you're on Apple Silicon (M1/M2/M3), ensure you're using Python compiled for ARM64:

# Check your Python architecture
python3 -c "import platform; print(platform.machine())"
# Should output: arm64

If you get x86_64 instead, reinstall Python from python.org with the native ARM64 installer.

Linux¶

For Debian/Ubuntu, you may need to install additional system dependencies:

sudo apt-get install build-essential python3-dev

Windows¶

Use PowerShell or Windows Terminal for best compatibility. The cmd.exe command prompt may have issues with certain dependencies.

Getting Help¶

If installation issues persist:

Check the GitHub Issues page
Share your Python version and platform: python3 --version && uname -a
Include the full error traceback
Open a new issue with details