Installation#

TorchFX can be installed either from the Python Package Index (PyPI) or by cloning the repository from GitHub. This guide covers system requirements, installation methods, platform-specific configuration, and dependency management.

Quick Start

For most users, a simple pip install torchfx is all you need to get started. For development or advanced configurations, see the sections below.

Purpose and Scope#

This document describes the installation procedures for TorchFX, including system requirements, installation methods, platform-specific PyTorch configuration, and dependency management. For a quick start guide with minimal setup, see Getting Started. For details on the development environment setup, see Developer Documentation.

System Requirements#

TorchFX requires Python 3.10 or higher. The library is designed to run on multiple platforms with different hardware acceleration capabilities:

Platform	PyTorch Backend	CUDA Support
Linux	CUDA 12.4	Yes
macOS	CPU	No
Windows	CPU	No

Note

The platform-specific PyTorch configuration is automatically handled using the uv package manager’s source selection mechanism based on your operating system.

Core Dependencies#

TorchFX requires the following Python packages:

torch>=2.6.0 - PyTorch tensor library
torchaudio>=2.6.0 - Audio I/O and transforms
numpy>=2.2.4 - Numerical computing
scipy>=1.15.2 - Signal processing algorithms
soundfile>=0.13.1 - Audio file reading/writing
annotated-types>=0.7.0 - Type annotation support

Tip

These dependencies are installed automatically when you install TorchFX via pip or uv.

Installation Methods#

Installing from PyPI#

The simplest installation method is through PyPI:

pip install torchfx

This installs the latest stable release published on PyPI, along with all required dependencies. On Linux systems, this will attempt to install CUDA 12.4-enabled PyTorch; on macOS and Windows, it will install CPU-only versions.

Installing from Source#

To install the latest development version of TorchFX directly from GitHub, follow these steps:

git clone https://github.com/matteospanio/torchfx
cd torchfx
pip install -e .

This approach is useful if you plan to contribute to the project or want access to the latest features and updates that may not yet be available on PyPI.

Installation from Source with uv#

For development or to use the latest unreleased features with reproducible builds, install from source using the uv package manager:

# Install uv if not already installed
pip install uv

# Clone the repository
git clone https://github.com/matteospanio/torchfx
cd torchfx

# Install in editable mode with all dependencies
uv sync

The uv sync command reads pyproject.toml and uv.lock to install all dependencies with exact versions for reproducible builds.

Installation Workflow#

The following diagram illustrates the complete installation workflow for both PyPI and source-based installations:

        graph TB
    User["User"]

    subgraph "Installation Methods"
        PipInstall["pip install torchfx"]
        SourceInstall["Clone + uv sync"]
    end

    subgraph "PyPI Distribution"
        PyPI["PyPI Registry"]
        Wheel["torchfx-0.2.1-*.whl"]
    end

    subgraph "Source Installation"
        GitRepo["GitHub Repository<br/>matteospanio/torchfx"]
        PyProject["pyproject.toml<br/>Dependencies definition"]
        UVLock["uv.lock<br/>Locked versions"]
        UV["uv package manager"]
    end

    subgraph "Dependency Resolution"
        DepResolver["Platform Detection"]
        LinuxPath["Linux:<br/>pytorch-cu124 index"]
        NonLinuxPath["macOS/Windows:<br/>pytorch-cpu index"]
        PyTorchCUDA["torch 2.6.0+cu124"]
        PyTorchCPU["torch 2.6.0+cpu"]
        OtherDeps["numpy, scipy<br/>soundfile, torchaudio"]
    end

    subgraph "Installed Package"
        TorchFXPkg["torchfx package<br/>in site-packages"]
    end

    User -->|pip install| PipInstall
    User -->|git clone + uv sync| SourceInstall

    PipInstall --> PyPI
    PyPI --> Wheel
    Wheel --> DepResolver

    SourceInstall --> GitRepo
    GitRepo --> PyProject
    GitRepo --> UVLock
    PyProject --> UV
    UVLock --> UV
    UV --> DepResolver

    DepResolver -->|sys_platform == 'linux'| LinuxPath
    DepResolver -->|sys_platform != 'linux'| NonLinuxPath

    LinuxPath --> PyTorchCUDA
    NonLinuxPath --> PyTorchCPU

    PyTorchCUDA --> TorchFXPkg
    PyTorchCPU --> TorchFXPkg
    DepResolver --> OtherDeps
    OtherDeps --> TorchFXPkg

Platform-Specific PyTorch Configuration#

The uv package manager uses platform markers to select the appropriate PyTorch distribution. This configuration ensures that Linux users get CUDA-enabled builds while macOS and Windows users receive CPU-only builds.

PyTorch Source Selection Logic#

The following diagram shows how PyTorch sources are selected based on the platform:

        graph TD
    Start["Dependency Resolution Start"]

    PlatformCheck{"sys_platform == 'linux'?"}

    subgraph "Linux Path"
        CUDAIndex["[[tool.uv.index]]<br/>name = 'pytorch-cu124'<br/>url = download.pytorch.org/whl/cu124"]
        CUDASource["torch source:<br/>index = 'pytorch-cu124'<br/>marker = sys_platform == 'linux'"]
        CUDAPackage["torch 2.6.0+cu124<br/>torchaudio 2.6.0+cu124<br/>CUDA 12.4 support"]
    end

    subgraph "Non-Linux Path"
        CPUIndex["[[tool.uv.index]]<br/>name = 'pytorch-cpu'<br/>url = download.pytorch.org/whl/cpu"]
        CPUSource["torch source:<br/>index = 'pytorch-cpu'<br/>marker = sys_platform != 'linux'"]
        CPUPackage["torch 2.6.0+cpu<br/>torchaudio 2.6.0+cpu<br/>CPU-only"]
    end

    Result["Resolved torch package"]

    Start --> PlatformCheck
    PlatformCheck -->|Yes| CUDASource
    PlatformCheck -->|No| CPUSource

    CUDASource --> CUDAIndex
    CUDAIndex --> CUDAPackage
    CPUSource --> CPUIndex
    CPUIndex --> CPUPackage

    CUDAPackage --> Result
    CPUPackage --> Result

The platform detection uses Python’s sys_platform to determine which PyTorch index to use:

Linux systems: Resolves torch and torchaudio from the pytorch-cu124 index at https://download.pytorch.org/whl/cu124, providing CUDA 12.4 GPU acceleration.
macOS and Windows: Resolves from the pytorch-cpu index at https://download.pytorch.org/whl/cpu, providing CPU-only builds.

The explicit = true flag in the configuration ensures these indices are only used when explicitly specified by the source configuration.

GPU Support#

TorchFX is built on top of PyTorch, which means GPU support depends on your local PyTorch installation. To enable GPU acceleration:

Make sure you have a compatible NVIDIA GPU
Ensure you’re running on a Linux system (CUDA support is currently Linux-only in the default configuration)
Install PyTorch with CUDA support

If you need a specific CUDA version different from 12.4, you can manually install PyTorch:

# Example: Installing PyTorch with CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Replace cu121 with the correct CUDA version for your system. Visit the official PyTorch website for the correct installation command for your configuration.

Dependency Management with uv#

The project uses uv as its primary dependency manager, which provides faster dependency resolution and reproducible builds through lock files.

Dependency Resolution Components#

The following diagram illustrates how dependencies are resolved and installed:

        graph TB
    subgraph "Configuration Files"
        PyProject["pyproject.toml"]
        UVLock["uv.lock"]
    end

    subgraph "Dependency Specifications"
        CoreDeps["[project.dependencies]<br/>torch>=2.6.0<br/>torchaudio>=2.6.0<br/>numpy>=2.2.4<br/>scipy>=1.15.2<br/>soundfile>=0.13.1<br/>annotated-types>=0.7.0"]

        DevGroups["[dependency-groups]<br/>cli: typer<br/>dev: black, mypy, pytest, ruff<br/>docs: sphinx, sphinx-immaterial"]

        UVSources["[tool.uv.sources]<br/>Platform-specific torch sources"]

        UVIndices["[[tool.uv.index]]<br/>pytorch-cpu<br/>pytorch-cu124"]
    end

    subgraph "Resolution Process"
        UVResolver["uv resolver engine"]
        PlatformDetect["Platform detection<br/>sys_platform"]
        VersionConstraints["Version constraint solver"]
    end

    subgraph "Lock File"
        LockedVersions["Exact package versions<br/>with hashes"]
        ResolvedDeps["Resolved dependency tree"]
    end

    subgraph "Installation"
        Download["Download packages"]
        Install["Install to environment"]
    end

    PyProject --> CoreDeps
    PyProject --> DevGroups
    PyProject --> UVSources
    PyProject --> UVIndices

    CoreDeps --> UVResolver
    DevGroups --> UVResolver
    UVSources --> PlatformDetect
    UVIndices --> PlatformDetect

    UVResolver --> VersionConstraints
    PlatformDetect --> VersionConstraints

    VersionConstraints --> LockedVersions
    VersionConstraints --> ResolvedDeps

    LockedVersions --> UVLock
    ResolvedDeps --> UVLock

    UVLock --> Download
    Download --> Install

Dependency Groups#

The project defines optional dependency groups for different use cases:

Group	Purpose	Key Packages
`cli`	Command-line interface	`typer>=0.16.0`
`dev`	Development tools	`black`, `mypy`, `pytest`, `ruff`, `coverage`, `scalene`
`docs`	Documentation building	`sphinx>=8.1.3`, `sphinx-immaterial>=0.13.5`

To install with specific groups:

# Install with dev dependencies
uv sync --group dev

# Install with all groups
uv sync --all-groups

# Install only docs dependencies
uv sync --group docs

Note

For contributors and developers, we recommend using uv sync --all-groups to install all development dependencies including testing, documentation, and CLI tools.

Developers#

If you are a developer and want to contribute to the TorchFX project, you can set up a development environment by following these steps:

Clone the repository:

git clone https://github.com/matteospanio/torchfx

Navigate to the project directory:
```
cd torchfx
```
Create a virtual environment (optional but recommended). The project is built using uv, hence we suggest using it:
```
# The flag --all-groups will install also dev dependencies
uv sync --all-groups
```

For more information on the development workflow, see Developer Documentation.

Build System#

The project uses hatchling as its build backend. The build system configuration is defined in pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

To build a distribution package:

# Using uv
uv build

# Or using standard tools
python -m build

This produces a wheel file (.whl) in the dist/ directory that can be distributed or installed with pip.

Verification#

After installation, verify that TorchFX is correctly installed and can import all core components.

Basic Installation Check#

To verify that the package has been correctly installed, run the following command in Python:

import torchfx
print(torchfx.__version__)  # Should print '0.2.1'

Comprehensive Verification#

For a more thorough verification, check that all core components can be imported and that PyTorch is correctly configured:

import torchfx
from torchfx import Wave, FX, Gain, Normalize
from torchfx.filter import Butterworth, LowPass

# Check version
print(torchfx.__version__)  # Should print '0.2.1'

# Verify PyTorch backend
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"PyTorch version: {torch.__version__}")

On Linux systems with NVIDIA GPUs, torch.cuda.is_available() should return True. On macOS and Windows, it will return False, indicating CPU-only operation.

Audio I/O Verification#

To verify audio I/O capabilities:

import torchaudio
print(f"torchaudio version: {torchaudio.__version__}")
print(f"Available backends: {torchaudio.list_audio_backends()}")

Expected output should show the available audio backends for your platform (e.g., soundfile, sox, ffmpeg).

Checking Installation#

You can perform a quick functional test to ensure TorchFX is working correctly:

import torchfx as fx

# Create a simple sine wave
wave = fx.Wave.from_function(lambda t: fx.sin(2 * fx.pi * 440 * t), duration=1.0, fs=44100)

# Apply a gain effect
gained = wave | fx.Gain(db=6.0)

# Verify the operation succeeded
print(f"Original wave: {wave.shape}")
print(f"Processed wave: {gained.shape}")
print(f"Sample rate: {gained.fs} Hz")

If this runs without errors, your installation is working correctly.

Troubleshooting#

PyTorch CUDA Version Mismatch#

If you have an existing PyTorch installation with a different CUDA version, you may need to uninstall it first:

pip uninstall torch torchaudio torchvision
uv sync --reinstall-package torch

This ensures that the correct PyTorch version is installed according to the platform-specific configuration.

Platform Detection Issues#

If the wrong PyTorch variant is installed, verify your platform:

import sys
print(f"Platform: {sys.platform}")

The marker sys_platform == 'linux' should be True on Linux systems. If you’re on Linux but getting the CPU-only version, check your Python installation and ensure sys.platform returns 'linux'.

Dependency Conflicts#

If you encounter dependency conflicts when using uv, regenerate the lock file:

rm uv.lock
uv lock
uv sync

This will resolve dependencies from scratch and create a new lock file with compatible versions.

Import Errors#

If you encounter import errors after installation, ensure that:

You’re using the correct Python environment where TorchFX was installed
All dependencies were installed successfully
There are no naming conflicts with other packages

You can verify your Python environment:

which python
pip list | grep torchfx

Audio Backend Issues#

If you encounter issues loading audio files, ensure that soundfile is properly installed:

pip install soundfile --upgrade

On some systems, you may need to install system-level audio libraries:

# Ubuntu/Debian
sudo apt-get install libsndfile1

# macOS
brew install libsndfile

# Windows
# Usually included with soundfile package

Still Having Issues?

If you continue to experience problems, please:

Check the GitHub Issues for similar problems
Create a new issue with details about your system, Python version, and the error message
Include the output of pip list to show installed packages and versions

Next Steps#

Now that you have TorchFX installed, you can:

Follow the Getting Started guide to learn the basics
Explore Core Concepts to understand the fundamental concepts
Try the Tutorials for hands-on examples
Learn about GPU Acceleration for performance optimization