---
type: Guide
title: "Installation Guide"
description: >-
  Set up the React apps with Node.js and npm, the Python stack for the Streamlit
  apps with pip or the streamlit-plotly conda environment, a Jupyter kernel,
  optional CUDA acceleration and the Docker image, with troubleshooting tips.
resource: https://tyson-swetnam.github.io/fractal-notebooks/applications/installation/
tags: [app, react, streamlit, jupyter, cuda]
sources:
  - id: miniconda
    resource: https://docs.conda.io/en/latest/miniconda.html
    title: "Miniconda installation guide"
  - id: cuda-toolkit
    resource: https://developer.nvidia.com/cuda-downloads
    title: "NVIDIA CUDA Toolkit downloads"
generated:
  by: human:tswetnam
  at: "2025-12-14T00:00:00Z"
status: stable
---

# Installation Guide

<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.

This guide covers setting up the development environment for running fractal visualization applications locally.

## Prerequisites

### For React Applications

- **Node.js** (v16 or later)
- **npm** (v8 or later)
- Modern web browser with WebGL support

### For Python Applications

- **Python** (v3.8 or later)
- **pip** or **conda** package manager
- Optional: CUDA-capable GPU for accelerated computation

---

## React Application Setup

### 1. Clone the Repository

```bash
git clone https://github.com/tyson-swetnam/fractal-notebooks
cd fractal-notebooks/react
```

### 2. Install Dependencies

```bash
npm ci
```

### 3. Start Development Server

```bash
npm start
```

The application will be available at `http://localhost:33000`.

### 4. Build for Production

```bash
npm run build
```

### Available Scripts

| Command | Description |
|---------|-------------|
| `npm start` | Start development server |
| `npm run build` | Create production build |
| `npm run type-check` | Run TypeScript type checking |
| `npm run lint` | Run ESLint |

---

## Python Environment Setup

### Option 1: Using pip

```bash
pip install streamlit numpy scipy matplotlib plotly pillow imageio
```

The four tree-ring apps (`app.py` to `app4.py`) also need `pandas`, and `app3.py` needs `shapely`. The repository's root `requirements.txt` is the documentation toolchain, not the app stack.

### Option 2: Using Conda with Mamba

1. **Install Miniconda**

    === "macOS"
        ```bash
        curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
        bash Miniconda3-latest-MacOSX-x86_64.sh
        ```

    === "Linux"
        ```bash
        curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
        bash Miniconda3-latest-Linux-x86_64.sh
        ```

    === "Windows"
        Download from [Miniconda website](https://docs.conda.io/en/latest/miniconda.html) and run the installer.

2. **Install Mamba (faster solver)**

    ```bash
    conda install mamba -n base -c conda-forge
    ```

3. **Create Environment**

    ```bash
    cd fractal-notebooks/docs/notebooks
    mamba env create -f streamlit-plotly.yaml
    ```

4. **Activate Environment**

    ```bash
    mamba activate streamlit-plotly
    ```

---

## Running Streamlit Applications

After setting up the Python environment:

```bash
cd apps
streamlit run tree_roots_3d.py
```

### Available Applications

| File | Description |
|------|-------------|
| `tree_roots_3d.py` | Interactive 3D tree with crown and root systems |
| `cones.py` | Year-by-year tree growth simulator built from cones |
| `bacterial_dla_app.py` | Animated bacterial diffusion-limited aggregation |
| `yeast_d3js.py` | D3.js yeast colony simulation |

The full catalogue of the twelve Streamlit apps, and of the matplotlib/PIL scripts (`mandelbrot.py`, `julia.py`, `branching_tree.py`, `pythagoras_tree.py`) that are run with `python` rather than `streamlit`, is on the [Streamlit Apps](streamlit-apps.md) page.

---

## Jupyter Notebook Setup

### Install Jupyter Kernel

```bash
mamba activate streamlit-plotly
mamba install -c conda-forge jupyterlab ipykernel
python -m ipykernel install --name streamlit-plotly --display-name "Python (streamlit-plotly)"
```

### Launch JupyterLab

```bash
jupyter lab
```

Navigate to the `docs/notebooks/` directory to access the example notebooks.

---

## GPU Acceleration (Optional)

### CUDA Setup for PyTorch

For GPU-accelerated computation with PyTorch:

=== "Linux/Windows"
    1. Visit [NVIDIA CUDA Toolkit](https://developer.nvidia.com/cuda-downloads)
    2. Select your OS and architecture
    3. Follow installation instructions
    4. Verify: `nvcc --version`

=== "macOS"
    CUDA is not supported on macOS. Use Metal Performance Shaders (MPS) with PyTorch 2.0+.

### Verify GPU Access

```python
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"Device count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"Device name: {torch.cuda.get_device_name(0)}")
```

---

## Docker Setup

For containerized deployment:

```bash
# from the repository root (the Dockerfile copies apps/)
docker build -f docker/Dockerfile -t fractal-app .
docker run -p 8501:8501 fractal-app
```

---

## Troubleshooting

### Common Issues

**Node.js version mismatch**
```bash
nvm install 18
nvm use 18
```

**Python package conflicts**
```bash
mamba env remove -n streamlit-plotly
mamba env create -f streamlit-plotly.yaml
```

**WebGL not available**
- Update graphics drivers
- Try a different browser
- Check browser WebGL support at [get.webgl.org](https://get.webgl.org)

### Getting Help

- Open an issue on [GitHub](https://github.com/tyson-swetnam/fractal-notebooks/issues)
- Check existing documentation in this guide