Skip to content

Installation

This guide covers everything you need to install and set up PyFDS on your system.

Requirements

Python Version

PyFDS requires Python 3.11 or higher. Check your Python version:

python --version

If you need to install or upgrade Python, visit python.org/downloads.

System Requirements

  • Operating System: Linux, macOS, or Windows
  • Memory: Minimum 4GB RAM (8GB+ recommended for larger simulations)
  • Storage: ~500MB for PyFDS and dependencies

Optional: FDS Installation

FDS Required for Execution

PyFDS can create and validate FDS input files without FDS installed. However, to actually run simulations, you need FDS installed on your system.

To install FDS:

  1. Visit the FDS-SMV Downloads page
  2. Download the installer for your operating system
  3. Follow the installation instructions
  4. Verify installation: fds -v

Installation Methods

uv is a fast Python package manager. This is the recommended installation method.

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv add pyfds

# Create a new project with PyFDS
mkdir my-fds-project
cd my-fds-project
uv init
uv add pyfds

# Run Python with PyFDS
uv run python your_script.py

Method 2: Using pip

Standard installation using pip:

pip install pyfds

For a specific version:

pip install pyfds==0.1.0

Method 3: From Source (Development)

For development or to get the latest features:

# Clone the repository
git clone https://github.com/GraysonBellamy/pyfds.git
cd pyfds

# Install with development dependencies
uv sync --extra dev

# Clone the repository
git clone https://github.com/GraysonBellamy/pyfds.git
cd pyfds

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Verifying Installation

After installation, verify that PyFDS is installed correctly:

import pyfds

print(f"PyFDS version: {pyfds.__version__}")
print("Installation successful!")

python -c "import pyfds; print(pyfds.__version__)"

Expected output: 

PyFDS version: 0.1.0
Installation successful!

Check Available Components

Verify that all major components are available:

from pyfds import (
    Simulation,      # Main simulation class
    Results,         # Results analysis
    FDSRunner,       # Execution engine
    Validator,       # Validation tools
)

print("All components imported successfully!")

Dependencies

PyFDS automatically installs these dependencies:

Core Dependencies

Package Version Purpose
numpy ≥2.3.5 Numerical computations
polars ≥1.35.2 Fast DataFrame operations
pydantic ≥2.12.4 Data validation
matplotlib ≥3.10.7 Plotting and visualization
h5py ≥3.15.1 HDF5 file reading
xarray ≥2025.11.0 Multi-dimensional arrays
click ≥8.3.1 CLI interface
tqdm ≥4.67.1 Progress bars

Development Dependencies (Optional)

For development work, additional dependencies are installed:

Package Purpose
pytest Testing framework
pytest-cov Coverage reporting
pytest-benchmark Performance testing
ruff Linting and formatting
mypy Type checking
pre-commit Git hooks

Virtual Environments

Use Virtual Environments

Always use a virtual environment to avoid dependency conflicts.

Using venv (Built-in)

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install PyFDS
pip install pyfds

Using conda

# Create conda environment
conda create -n pyfds python=3.11
conda activate pyfds

# Install PyFDS
pip install pyfds

Using uv (Automatic)

uv automatically manages virtual environments for you:

# uv creates and manages .venv automatically
uv add pyfds
uv run python your_script.py

Platform-Specific Notes

Linux

PyFDS works out-of-the-box on most Linux distributions.

# Ubuntu/Debian
sudo apt update
python3 --version  # Verify Python 3.11+

# Install PyFDS
pip install pyfds

macOS

# Check Python version
python3 --version

# Install PyFDS
pip3 install pyfds

macOS Note

On macOS, you may need to use python3 and pip3 instead of python and pip.

Windows

# Check Python version
python --version

# Install PyFDS
pip install pyfds

Windows Path

Ensure Python is in your system PATH. During Python installation, check "Add Python to PATH".

Upgrading PyFDS

To upgrade to the latest version:

uv add --upgrade pyfds

pip install --upgrade pyfds

To upgrade to a specific version:

pip install --upgrade pyfds==0.2.0

Uninstalling

To remove PyFDS:

uv remove pyfds

pip uninstall pyfds

Troubleshooting Installation

Common Issues

ImportError: No module named 'pyfds'

Solution: PyFDS is not installed in the current Python environment.

# Verify installation
pip list | grep pyfds

# Reinstall if needed
pip install pyfds
Version conflict errors

Solution: Use a fresh virtual environment.

python -m venv fresh-env
source fresh-env/bin/activate  # or fresh-env\Scripts\activate on Windows
pip install pyfds
Permission errors on Linux/macOS

Solution: Don't use sudo with pip. Use virtual environments or --user flag.

pip install --user pyfds
SSL certificate errors

Solution: Update pip and try again.

pip install --upgrade pip
pip install pyfds

Getting Help

If you encounter installation issues:

  1. Check the Troubleshooting Guide
  2. Search GitHub Issues
  3. Ask in GitHub Discussions
  4. Open a new issue

Next Steps

Now that PyFDS is installed, you're ready to create your first simulation!

Quick Start Tutorial →