Skip to content

Installation

The website documents main, which can be ahead of the released package. Check the release notes before using an unreleased API, and retain your package version or source commit alongside the HEC-RAS version in reproducible workflows.

Requirements

  • Python: 3.10 or higher (3.13 recommended for new installations)
  • HEC-RAS: 6.0+ recommended (3.x-5.x supported via RasControl)
  • Operating System: Windows (for full HEC-RAS execution), Linux (map generation via Wine), Mac (HDF analysis only)

Prerequisites

uv is a fast Python package manager required for Claude Code agent operations and recommended for all users:

PowerShell
irm https://astral.sh/uv/install.ps1 | iex
Bash
curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:

Bash
uv --version  # Should show: uv 0.5.x or later

Why uv?

  • 10-100x faster than pip for package installation
  • Required for Claude Code agent scripts and skills
  • Enables one-off script execution with uvx
  • Better dependency resolution

For Jupyter notebook work, we recommend Anaconda:

Standard Environment Names

RAS Commander uses two standard environment names:

Environment Purpose Install Type
RasCommander Standard user environment pip package
rascmdr_local Development environment editable install

Install from PyPI (Most Users)

Environment name: RasCommander

Use this if: You're using ras-commander, NOT editing its source code.

Bash
# Create environment
conda create -n RasCommander python=3.13
conda activate RasCommander

# Install ras-commander with the dependencies the examples and notebooks use
pip install "ras-commander[full]"

# Install Jupyter (for notebooks)
pip install jupyter ipykernel
python -m ipykernel install --user --name RasCommander --display-name "Python (RasCommander)"

Quick Install

For a quick install without Jupyter:

Bash
pip install --upgrade "ras-commander[full]"

Installation Profiles

These are installed automatically with pip install ras-commander:

Bash
h5py numpy pandas
ras-commander-fast-hdf   # Windows x64, Linux x64 and macOS arm64 only

ras-commander-fast-hdf is ras-commander's default HDF engine, written in Rust. On the three platforms above, pip installs its binary wheel; no Rust toolchain or HDF5 C library is needed. Public Hdf* results are identical to the h5py reference implementation, and large reads, such as 2D cell polygons and mesh time series on large meshes, are faster. In the default auto mode, any read the engine refuses uses h5py.

  • Turn it off: set RAS_COMMANDER_FAST_HDF=h5py before the first HDF read. Every read then uses h5py.
  • Other platforms (for example Linux aarch64, macOS x86_64 or Windows ARM64): pip does not install the engine, and ras-commander uses h5py for every read with the same results. pip install "ras-commander[fast]" requests the engine anyway and builds it from source, which needs Rust.
  • Linux x64 without a compatible wheel (glibc older than 2.28, or musl, for example Alpine) and free-threaded CPython builds: the dependency still applies, so pip tries to build the engine from source. Install a Rust toolchain, or run pip install h5py numpy pandas and then pip install --no-deps ras-commander to use h5py.
  • Check which engine is available: python -c "from ras_commander import fast_hdf; print(fast_hdf.available())" prints True when the native engine is installed and compatible.

The fast and fast-hdf extras are no longer needed; they remain so existing install commands keep working. See Native Rust HDF engine for modes, qualification and performance.

The core install supports project inventory: init_ras_project() and the project DataFrames, including geometry counts read from geometry HDF files. Downloading example projects with RasExamples.extract_project() also needs requests. Without it, the call raises an ImportError that names the full extra. Geospatial, plotting, and precipitation APIs need the full extra.

For command-line HEC-RAS execution and compute-message parsing without RasControl/COM or the full geospatial stack:

Bash
pip install "ras-commander[compute]"

The execution extra is an alias for compute. Both add psutil and, on Windows, pywin32 for the normal process and dialog supervision used by RasCmdr.compute_plan().

The compute install reads results that are returned as pandas DataFrames. Examples are plan-level results from HdfResultsPlan (compute messages, runtime, and volume accounting) and geometry-free 2D mesh summary values from HdfResultsMesh.get_mesh_summary_values(). The HDF result classes import without the optional packages. Functions that return an xarray object (time series such as HdfResultsMesh.get_mesh_timeseries() and HdfResultsXsec.get_xsec_timeseries()) need xarray. Functions that return a GeoDataFrame (such as HdfResultsMesh.get_mesh_max_ws() and HdfResultsMesh.get_mesh_max_depth()) need geopandas. Without the package, these functions raise an ImportError that names the package and the install command. Most per-cell readers also return a typed pandas table with include_geometry=False, which works without geopandas; see Typed tables without geometry. To add the complete results stack to a compute install:

Bash
pip install "ras-commander[compute,full]"

For the historical complete feature dependency set, including geospatial, plotting, scientific, precipitation, and remote-data dependencies:

Bash
pip install "ras-commander[full]"

Use ras-commander[all] when you also want every optional backend and integration. Extras are additive and can be combined.

Compute extra scope

The extra controls Python dependencies only; it does not install HEC-RAS or Wine. It preserves the normal RasCmdr.compute_plan() behavior, including project/result DataFrame refresh after execution. It does not expose a reduced-refresh execution mode and does not route computation through COM.

Optional Dependencies

Notebook Examples

Additional packages for running the example notebooks:

Bash
pip install rasterio pyproj

DSS File Operations

For reading HEC-DSS boundary condition files:

Bash
pip install pyjnius

Java Required

DSS operations require Java 8+ (JRE or JDK) installed on your system.

Linux/Wine (Headless RasProcess Workflows)

On Linux, RasProcess.exe can run under Wine for documented RasProcess workflows such as stored map generation (WSE, Depth, Velocity TIFs) and native reference validation of geometry associations. This enables headless CI/CD pipelines and cloud-based map or QA/QC workflows.

Requirements:

  • Wine 8.0+ (64-bit prefix)
  • .NET Framework 4.8 (installed via winetricks)
  • HEC-RAS DLLs copied from a Windows installation
Bash
# Step 1: Install Wine
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install -y wine wine64 wine32 winetricks cabextract

# Step 2: Create Wine prefix with .NET 4.8
export WINEPREFIX=/opt/hecras-wine
export WINEARCH=win64
wineboot --init
winetricks -q dotnet48      # ~15 min, installs .NET Framework 4.8
winetricks -q gdiplus       # Native GDI+ (required for System.Drawing)
winetricks -q corefonts     # Arial, Times New Roman, etc.

# Step 3: Copy HEC-RAS DLLs from a Windows machine
# From C:\Program Files (x86)\HEC\HEC-RAS\6.6\ copy all DLLs and the GDAL/ folder
# to /opt/hecras-wine/drive_c/HEC-RAS/6.6/

Detailed Setup Instructions

Run RasProcess.setup_wine_environment() in Python to print the complete list of required DLLs and step-by-step instructions.

Validated Environment

Verified on the CLB07 Proxmox container ras2cng-wine (Debian 13, Wine 11.0). Custom wine_executable paths or wrappers are supported; helper tools such as winepath are resolved automatically.

Scope

Wine support covers wrapped RasProcess.exe workflows. Full HEC-RAS simulation (Ras.exe) still requires Windows. Read-only HDF analysis works on Linux without Wine; native geometry association requires the applicable HEC-RAS/RASMapper runtime.

Verify installation:

Python
from ras_commander import RasProcess

# Check Wine environment is configured correctly
status = RasProcess.check_wine_environment()
print(status)

Usage (no code changes needed -- auto-detected):

Python
from ras_commander import RasProcess

# Same API as Windows -- Wine wrapping is automatic
results = RasProcess.store_maps(plan_number="01", wse=True, depth=True)
Python
# Optional native reference validator. This mutates the supplied HDF in place,
# so use it on a disposable copy or intentional validation target.
validation = RasProcess.validate_geometry_association_cli(
    "MyModel.g01.hdf",
    terrain_hdf_path="Terrain/ExistingTerrain.hdf",
    ras_version="7.0",
)
print(validation["passed"])

Remote Execution

For distributed computation across multiple machines:

Bash
# Individual backends
pip install paramiko      # SSH remote execution
pip install pywinrm       # WinRM remote execution
pip install docker        # Docker container execution
pip install boto3         # AWS EC2 execution
pip install azure-identity azure-mgmt-compute  # Azure execution

# Or install all at once
pip install ras-commander[remote-all]

Development Installation

Environment name: rascmdr_local

Use this if: You're editing ras-commander source code or contributing to the library.

Bash
# Clone the repository
git clone https://github.com/gpt-cmdr/ras-commander.git
cd ras-commander

# Create development environment
conda create -n rascmdr_local python=3.13
conda activate rascmdr_local

# Install in editable mode
pip install -e .

# Install Jupyter (for notebooks)
pip install jupyter ipykernel
python -m ipykernel install --user --name rascmdr_local --display-name "Python (rascmdr_local)"

Using uv for Development

For faster package installation during development:

Bash
uv venv .venv
.venv\Scripts\activate  # Windows
uv pip install -e .

Flexible Import Pattern

Scripts in the repository use this pattern to work both with installed packages and development mode:

Python
from pathlib import Path
import sys

try:
    from ras_commander import init_ras_project, RasCmdr
except ImportError:
    # Add parent directory to path for development
    sys.path.append(str(Path(__file__).resolve().parent.parent))
    from ras_commander import init_ras_project, RasCmdr

Verifying Installation

Python
import ras_commander
print(f"RAS Commander version: {ras_commander.__version__}")

# Test basic imports
from ras_commander import (
    init_ras_project,
    RasCmdr,
    RasPlan,
    RasExamples,
    ras
)
print("All imports successful!")

Troubleshooting

Dependency Conflicts with NumPy

If you encounter numpy-related errors:

Bash
# Clear local pip packages
# Windows: Delete C:\Users\<username>\AppData\Roaming\Python\

# Create fresh environment
python -m venv fresh_env
fresh_env\Scripts\activate
pip install ras-commander

HEC-RAS Not Found

If HEC-RAS execution fails:

  1. Verify HEC-RAS is installed (default: C:\Program Files\HEC\HEC-RAS\7.x\)
  2. Specify the full path to Ras.exe:
Python
init_ras_project("/path/to/project", r"D:\Programs\HEC\HEC-RAS\6.5\Ras.exe")

pywin32 Errors

For COM interface issues on Windows:

Bash
pip uninstall pywin32
pip install pywin32
python -c "import win32com.client"  # Test import