This guide covers installing PyPTV on Linux and macOS systems.
đź“ť Windows Users: See the Windows Installation Guide for platform-specific instructions.
Before installing PyPTV, ensure you have:
sudo apt update
sudo apt install -y build-essential cmake git pkg-config
sudo apt install -y libhdf5-dev
sudo dnf install -y gcc gcc-c++ cmake git pkg-config
sudo dnf install -y hdf5-devel
# Install Xcode Command Line Tools
xcode-select --install
# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install dependencies
brew install cmake pkg-config hdf5
The easiest way to install PyPTV is using the provided installation script:
# 1. Clone the repository
git clone https://github.com/openptv/pyptv.git
cd pyptv
# 2. Run the installation script
./install_pyptv.sh
# 3. Activate the environment
conda activate pyptv
The script will:
If you prefer manual control or need to customize the installation:
# 1. Clone the repository
git clone https://github.com/openptv/pyptv.git
cd pyptv
# 2. Create conda environment
conda env create -f environment.yml
conda activate pyptv
# 3. Install PyPTV
pip install -e .
For developers who want to contribute to PyPTV:
# 1. Fork and clone your fork
git clone https://github.com/yourusername/pyptv.git
cd pyptv
# 2. Create development environment
conda env create -f environment.yml
conda activate pyptv
# 3. Install in development mode with test dependencies
pip install -e ".[dev,test]"
# 4. Install pre-commit hooks
pre-commit install
Test your installation by running:
# Activate the environment
conda activate pyptv
# Test basic import
python -c "import pyptv; print('PyPTV installed successfully!')"
# Launch the GUI (should open without errors)
python -m pyptv.pyptv_gui
# Run the test suite
pytest tests/
## Testing: Headless vs GUI
PyPTV separates tests into two categories:
- **Headless tests** (no GUI): Located in `tests/`. These run in CI (GitHub Actions) and Docker, and do not require a display.
- **GUI-dependent tests**: Located in `tests_gui/`. These require a display and are run locally or with Xvfb.
To run all tests locally:
```bash
bash run_tests.sh
To run only headless tests (recommended for CI/Docker):
bash run_headless_tests.sh
For headless testing and reproducible builds, you can use Docker:
docker build -t pyptv-test .
docker run --rm pyptv-test
This runs only headless tests in a minimal environment, mimicking CI.
## Common Installation Issues
### Issue: "liboptv not found"
**Solution**: The OpenPTV library needs to be built and installed. Try:
```bash
conda activate pyptv
cd pyptv
./install_pyptv.sh
Solution: Install HDF5 development packages:
# Ubuntu/Debian
sudo apt install libhdf5-dev
# macOS
brew install hdf5
Solution: Ensure you have write permissions and try:
# Clean previous builds
rm -rf build/ dist/ *.egg-info/
./install_pyptv.sh
Every time you want to use PyPTV:
conda activate pyptv
To get the latest changes:
conda activate pyptv
cd pyptv
git pull origin main
pip install -e .
To completely remove PyPTV:
conda env remove -n pyptv
rm -rf pyptv/ # Remove the source directory
Once PyPTV is installed:
If you encounter installation issues:
Next: Quick Start Guide or Windows Installation