Skip to content

Installation#

This guide covers all the ways to install the oxo-flow binary on your system.

Requirements#

  • Operating system: Linux (x86_64, aarch64) or macOS (Apple Silicon, Intel)
  • Disk space: ~50 MB for the binary
  • Optional: Rust toolchain (1.85+) if building from source

Runtime dependencies

oxo-flow itself has no runtime dependencies — it is a single static binary. However, the tools your workflows call (e.g., bwa, samtools, GATK) must be available either on your $PATH or through an environment manager (conda, docker, etc.) declared in your .oxoflow file.

If you don't have Rust installed, use the official installer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

cargo install oxo-flow-cli

This builds the latest published release and places the oxo-flow binary in ~/.cargo/bin/.

Verify PATH: Ensure ~/.cargo/bin/ is in your $PATH. You can check with: 

echo $PATH | grep -q ".cargo/bin" || echo 'Add to PATH: export PATH="$HOME/.cargo/bin:$PATH"'

Verify the installation:

oxo-flow --version
# oxo-flow 0.6.0

Updating

Run the same cargo install oxo-flow-cli command to update to the latest version. Cargo will rebuild if a newer version is available.

Option 2 — Build from Source#

Clone the repository and build the workspace:

git clone https://github.com/Traitome/oxo-flow.git
cd oxo-flow
cargo build --release

The binary is at target/release/oxo-flow. Copy it to a directory on your $PATH:

cp target/release/oxo-flow ~/.local/bin/

Development build#

For faster compile times during development (without optimizations):

cargo build
# Binary at: target/debug/oxo-flow

Option 3 — Download Pre-built Binary#

Pre-built binaries are available from the GitHub Releases page.

curl -LO https://github.com/Traitome/oxo-flow/releases/latest/download/oxo-flow-linux-x86_64.tar.gz
tar xzf oxo-flow-linux-x86_64.tar.gz
chmod +x oxo-flow
mv oxo-flow ~/.local/bin/

curl -LO https://github.com/Traitome/oxo-flow/releases/latest/download/oxo-flow-macos-aarch64.tar.gz
tar xzf oxo-flow-macos-aarch64.tar.gz
chmod +x oxo-flow
mv oxo-flow /usr/local/bin/  # Or another folder in your PATH

Optional Dependencies#

Graphviz (for Visualization)#

The oxo-flow graph command outputs workflows in DOT format. To render these graphs as images (PNG, SVG, etc.), you need to install Graphviz.

brew install graphviz

sudo apt install graphviz

conda install -c conda-forge graphviz

Shell Completions#

oxo-flow can generate shell completions for Bash, Zsh, Fish, Elvish, and PowerShell:

oxo-flow completions bash > ~/.local/share/bash-completion/completions/oxo-flow

oxo-flow completions zsh > ~/.zfunc/_oxo-flow
# Add to .zshrc: fpath+=~/.zfunc && autoload -Uz compinit && compinit

oxo-flow completions fish > ~/.config/fish/completions/oxo-flow.fish

Verify Installation#

After installation, confirm everything is working:

# Check version
oxo-flow --version

# Show help
oxo-flow --help

# Initialize a test project
oxo-flow init my-test-pipeline
cd my-test-pipeline
oxo-flow validate my-test-pipeline.oxoflow

Expected output:

✓ my-test-pipeline.oxoflow — 0 rules, 0 dependencies

Next Steps#