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¶
Install Astral uv (Recommended)¶
uv is a fast Python package manager required for Claude Code agent operations and recommended for all users:
Verify installation:
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
Install Anaconda (Recommended for Notebooks)¶
For Jupyter notebook work, we recommend Anaconda:
- Download: https://www.anaconda.com/download
- Verify:
conda --version
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.
# 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)"
Installation Profiles¶
These are installed automatically with pip install ras-commander:
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=h5pybefore 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 pandasand thenpip install --no-deps ras-commanderto use h5py. - Check which engine is available:
python -c "from ras_commander import fast_hdf; print(fast_hdf.available())"printsTruewhen 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:
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:
For the historical complete feature dependency set, including geospatial, plotting, scientific, precipitation, and remote-data dependencies:
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:
DSS File Operations¶
For reading HEC-DSS boundary condition files:
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
# 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:
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):
from ras_commander import RasProcess
# Same API as Windows -- Wine wrapping is automatic
results = RasProcess.store_maps(plan_number="01", wse=True, depth=True)
# 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:
# 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.
# 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:
Flexible Import Pattern¶
Scripts in the repository use this pattern to work both with installed packages and development mode:
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¶
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:
# 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:
- Verify HEC-RAS is installed (default:
C:\Program Files\HEC\HEC-RAS\7.x\) - Specify the full path to Ras.exe:
pywin32 Errors¶
For COM interface issues on Windows: