Installation Guide¶
This guide walks you through setting up the Portfolio Management Toolkit on your system.
Prerequisites¶
- Python 3.12 or higher (required)
- Git (for cloning the repository)
- 8GB RAM minimum (16GB recommended for large backtests)
- 10GB free disk space (for data and outputs)
System Requirements¶
Supported Operating Systems¶
- ✅ Linux (Ubuntu 20.04+, Debian 11+)
- ✅ macOS (12.0+)
- ✅ Windows (via WSL2 recommended)
Python Version¶
This project requires Python 3.12 or higher. Verify your Python version:
If you need to install Python 3.12:
Ubuntu/Debian:
macOS (with Homebrew):
Windows (WSL2):
Technology Stack¶
The toolkit is built on the package versions documented in stack.yaml (see the application_libraries section). Key categories include:
Runtime Libraries¶
| Library | Version spec | Source |
|---|---|---|
| pandas | >=2.3,<3.0 | requirements.txt |
| numpy | >=2.0.0 | requirements.txt |
| PyYAML | >=6.0 | requirements.txt |
| scipy | >=1.3 | requirements.txt |
| cvxpy | >=1.1.19 | requirements.txt |
| ecos | >=2.0.14,<3.0.0 | requirements.txt |
| empyrical-reloaded | >=0.5.0 | requirements.txt |
| plotly | >=5.0.0,<6.0.0 | requirements.txt |
| PyPortfolioOpt | >=1.5.0 | requirements.txt |
| riskparityportfolio | >=0.2 | requirements.txt |
| tqdm | >=4.65.0 | requirements.txt |
| jax | >=0.4.0 | requirements.txt |
| jaxlib | >=0.4.0 | requirements.txt |
Optional Extras¶
| Library | Purpose |
|---|---|
polars >=0.19.0, pyarrow >=14.0.0 |
Fast I/O backend for CSV ingestion (enabled via --fast-io) |
Development & Tooling¶
| Tool | Why it exists |
|---|---|
ruff >=0.8.0 |
Formatter/linter + import sorter |
pre-commit >=4.0.0 |
Gatekeeper for lint/type formatting before commits |
bandit >=1.7.0 |
Security checks |
pyupgrade >=3.15.0 |
Modern syntax migrations |
mypy >=1.11.0 + pandas-stubs >=2.2.0, types-PyYAML >=6.0.12, types-tqdm |
Static typing |
pytest >=8.0.0, pytest-xdist, pytest-benchmark, hypothesis, pytest-timeout, pytest-randomly |
Test suite |
Required Packages¶
These sections mirror the actual requirements.txt files so the docs rebuild always show the current dependency set.
Core runtime requirements¶
pandas>=2.3,<3.0
numpy>=2.0.0
PyYAML>=6.0
scipy>=1.3
cvxpy>=1.1.19
ecos>=2.0.14,<3.0.0
empyrical-reloaded>=0.5.0
plotly>=5.0.0,<6.0.0
PyPortfolioOpt>=1.5.0
riskparityportfolio>=0.2
tqdm>=4.65.0
jax>=0.4.0
jaxlib>=0.4.0
Development & testing requirements¶
# Ruff: Single tool for formatting and linting (replaces black, isort, flake8, etc.)
ruff>=0.8.0
# Pre-commit framework
pre-commit>=4.0.0
# Python syntax upgrades
pyupgrade>=3.15.0
# Type checking
mypy>=1.11.0
pandas-stubs>=2.2.0
types-PyYAML>=6.0.12
types-tqdm
# Typings for Markdown (used by mkdocs extensions)
types-Markdown>=3.10.0.20251106
# Testing
pytest>=8.0.0
pytest-xdist>=3.5.0
pytest-timeout>=2.2.0
pytest-randomly>=3.15.0
pytest-benchmark>=4.0.0
# Property-based testing
hypothesis>=6.100.0
# Security linting
bandit>=1.7.0
# Architecture validation
import-linter>=2.0.0
pytest-archon>=0.0.7
# Dependency hygiene & security
deptry>=0.20.0
pip-audit>=2.7.0
# Architecture visualization
pydeps>=1.12.0
pydot>=3.0.0
# Documentation
mdformat>=0.7.17
gitlint>=0.19.0
# Markdown extensions (include directive)
pymdown-extensions>=10.16.1
# MkDocs: Documentation site generator
mkdocs>=1.6.0
mkdocs-material>=9.5.0
mkdocstrings[python]>=0.26.0
mkdocs-mermaid2-plugin>=1.1.0
mkdocs-git-revision-date-localized-plugin>=1.2.0
# Optional: Fast I/O dependencies (needed for type checking)
polars>=0.19.0
pyarrow>=14.0.0
Installation Steps¶
1. Clone the Repository¶
2. Install Dependencies¶
Option A: User Installation (Recommended)
# Install all dependencies
pip install --user -r requirements.txt
pip install --user -r requirements-dev.txt
Option B: Virtual Environment
# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
3. Verify Installation¶
# Run tests to verify setup
pytest tests/ -m "not integration" --maxfail=5
# Check type safety
mypy src/
# Check code quality
ruff check src/
All checks should pass with no errors.
4. Set Up Data Directory¶
# Create data directories
mkdir -p data/stooq
mkdir -p data/processed
mkdir -p data/metadata
# (Optional) Download sample data
# Add instructions for sample data if available
5. Configure Git Hooks (Optional but Recommended)¶
Development Tools¶
Recommended VS Code Extensions¶
If using VS Code, install these extensions:
- Python (ms-python.python)
- Pylance (ms-python.vscode-pylance)
- Ruff (charliermarsh.ruff)
- GitLens (eamodio.gitlens)
Makefile Commands¶
The project includes a Makefile for common tasks:
make help # Show all available commands
make install # Install all dependencies
make fmt # Format code with Ruff
make lint # Lint code with Ruff
make type # Type check with MyPy
make test # Run all tests
make test-unit # Run unit tests only
make docs # Serve documentation locally
Verification¶
Run this quick verification script:
python -c "
import sys
print(f'Python version: {sys.version}')
try:
import pandas as pd
import numpy as np
import yaml
from portfolio_management.core import config
print('✅ All core imports successful')
except ImportError as e:
print(f'❌ Import failed: {e}')
"
Expected output:
Troubleshooting¶
Issue: "Module not found" errors¶
Solution: Ensure you're in the repository root and have installed all dependencies:
Issue: MyPy errors about missing stubs¶
Solution: Install type stub packages:
Issue: Pre-commit hooks fail¶
Solution: Update hooks and run formatting:
Issue: Tests fail with "No module named portfolio_management"¶
Solution: Ensure repository root is in PYTHONPATH:
Next Steps¶
Once installation is complete:
- First Steps Tutorial - Run your first backtest
- Quick Start Guide - 5-minute overview
- Workflow Guide - Detailed workflows
Getting Help¶
If you encounter issues:
- Check Troubleshooting Guide
- Check Error Reference
- Search GitHub Issues
- Create a new issue with details
Updating¶
To update to the latest version:
Uninstallation¶
To remove the toolkit: