Skip to content

Installation Guide

This guide covers different methods for installing the HeavyTails library.

Requirements

HeavyTails has one dependency and requires:

  • Python 3.10 or higher
  • NumPy 1.24 or higher

!!! tip "One dependency" NumPy is required. It was optional through 0.4.0, and requiring it is why the next release is 0.5.0 rather than 0.4.1 — the library was pure Python, which kept it inspectable but meant evaluating a density over a hundred thousand points cost a hundred thousand interpreter round trips. The trade was worth making:

- **Fast** - a density over a million points takes about 20 milliseconds
- **Still inspectable** - the formulas are ordinary NumPy expressions
- **Still few moving parts** - one dependency, and no compiler needed
- **Reproducible** - a seeded sample is unchanged by the rewrite

Installation Methods

The simplest method is to install from the Python Package Index using pip:

pip install heavytails

To upgrade to the latest version:

pip install --upgrade heavytails

Method 2: Install with Poetry

If you use Poetry for dependency management:

poetry add heavytails

Method 3: Development Installation

For contributors or those who want to modify the source code:

# Clone the repository
git clone https://github.com/diogoribeiro7/heavytails.git
cd heavytails

# Install with Poetry (recommended for development)
poetry install

# Or install with pip in editable mode
pip install -e .

Method 4: Direct Source Installation

Download and install directly from source:

# Download the latest release
wget https://github.com/diogoribeiro7/heavytails/archive/refs/heads/main.zip
unzip main.zip
cd heavytails-main

# Install
pip install .

Verify Installation

After installation, verify that HeavyTails is working correctly:

# Test basic import
import heavytails

# Check version
print(heavytails.__version__)

# Test a simple distribution
from heavytails import Pareto

pareto = Pareto(alpha=2.0, xm=1.0)
samples = pareto.rvs(10, seed=42)
print(f"Sample values: {samples}")

Expected output:

0.1.0
Sample values: [1.234, 2.456, 1.789, ...]

Installation for Different Use Cases

For Academic Research

# Standard installation
pip install heavytails

# Verify numerical accuracy
python -c "from heavytails import Pareto; p = Pareto(2.0, 1.0); print(p.mean())"
# Expected: 2.0

For Financial Applications

# Install HeavyTails
pip install heavytails

# Optional: Install visualization tools (not required by HeavyTails)
pip install matplotlib pandas

For Teaching

# Install in user space (no admin required)
pip install --user heavytails

# Or create a virtual environment for the course
python -m venv heavytails_course
source heavytails_course/bin/activate  # On Windows: heavytails_course\Scripts\activate
pip install heavytails

Using a virtual environment keeps your Python installation clean:

```bash
# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate

# Install HeavyTails
pip install heavytails

# Deactivate when done
deactivate
```

```bash
# Create virtual environment
python -m venv venv

# Activate it
venv\Scripts\activate

# Install HeavyTails
pip install heavytails

# Deactivate when done
deactivate
```

```bash
# Poetry automatically creates and manages virtual environments
poetry init
poetry add heavytails
poetry shell  # Activate the environment
```

Optional Dependencies

Beyond NumPy, which is required, you may want to install these for enhanced functionality:

For Visualization

pip install matplotlib

Enables plotting capabilities:

from heavytails import Pareto
import matplotlib.pyplot as plt
import numpy as np

pareto = Pareto(alpha=2.0, xm=1.0)
x = np.logspace(0, 2, 100)
plt.loglog(x, [pareto.pdf(xi) for xi in x])
plt.xlabel('x')
plt.ylabel('PDF')
plt.title('Pareto PDF')
plt.show()

For Data Analysis

pip install pandas numpy

Useful for working with real datasets:

import pandas as pd
from heavytails import StudentT
from heavytails.tail_index import hill_estimator

# Load financial data
returns = pd.read_csv('stock_returns.csv')['return'].values

# Estimate tail index
gamma = hill_estimator(returns, k=100)
print(f"Tail index estimate: {1/gamma:.2f}")

For Jupyter Notebooks

pip install jupyter notebook

Run HeavyTails in interactive notebooks:

jupyter notebook

Troubleshooting

ImportError: No module named 'heavytails'

Solution: Ensure you're using the correct Python environment:

# Check which Python you're using
which python  # On Linux/macOS
where python  # On Windows

# Check if heavytails is installed
pip list | grep heavytails

Permission Denied Error

Solution: Install in user space:

pip install --user heavytails

Or use a virtual environment (recommended).

Python Version Error

Solution: HeavyTails requires Python 3.8+. Check your version:

python --version

If you have an older version, upgrade Python or use pyenv/conda to manage multiple versions.

Docker Installation

For containerized environments:

FROM python:3.11-slim

# Install HeavyTails
RUN pip install heavytails

# Copy your analysis scripts
COPY analysis.py /app/
WORKDIR /app

CMD ["python", "analysis.py"]

Build and run:

docker build -t heavytails-analysis .
docker run heavytails-analysis

Next Steps

Now that HeavyTails is installed:

  1. Quick Start Tutorial - Get started in 10 minutes
  2. Basic Concepts - Understand heavy-tailed distributions
  3. Examples - See practical applications

Getting Help

If you encounter installation issues: