Skip to content

flox in 5 minutes

Flox is a virtual environment and package manager all in one. With Flox you create development environments that layer and replace dependencies just where it matters (Flox won't mess with your setup!), making them portable across the full software lifecycle.

Follow the quick start steps to see how easy it is to get started on any project, on any system, with an existing Flox environment.

Quick start

  1. Install flox.
  2. git clone https://github.com/flox-examples/rust-env-demo.git
  3. cd rust-env-demo to enter the project directory where a flox environment has been pre-configured.
  4. flox activate to layer this project's dependencies onto current shell with a single command.
  5. cargo run to play with one of the rust dependencies that came with this project.
  6. flox search just to search for packages.
  7. flox install just to install the missing dependency.
  8. just profile to test the newly installed dependency by creating a flame graph.
  9. exit to leave the environment.

Detail about each of these steps is below.

Installing Flox

Start by installing flox.

Clone the example rust project

Clone the rust-env-demo repository and cd into it. This repository contains a Rust crate (package) that displays raw HTML for the Rust homepage and a Flox environment for working as a developer on the project.

$ git clone https://github.com/flox-examples/rust-env-demo.git
Cloning into 'rust-env-demo'...
Resolving deltas: ...
...
$ cd rust-env-demo

Activate the environment

Run flox activate to enter the development environment defined in the repository's .flox directory:

$ flox activate
flox [rust-env-demo] $ which cargo
/nix/store/...-auditable-cargo-.../bin/cargo

Let's build and run the crate with cargo run to verify that everything is working properly:

flox [rust-env-demo] $ cargo run
...
     Running `target/debug/rust-env-demo`
<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="utf-8">
    <title>...Rust Programming Language...</title>
...

List the environment's contents

To see a list of everything in this environment, run flox list. The Flox command line interface (CLI) has made all the dependencies this project needs available to your terminal as long as we are inside the environment.

flox [rust-env-demo] $ flox list
cargo: cargo (1.69.0)
cargo-flamegraph: cargo-flamegraph (0.6.3)
cargo-semver-checks: cargo-semver-checks (0.20.1)
cargo-watch: cargo-watch (8.4.0)
clippy: clippy (1.69.0)
rust-analyzer: rust-analyzer (2023-05-15)
rustc: rustc (1.69.0)
rustfmt: rustfmt (1.69.0)

Use the dependencies like normal

Let's see if Rust's linter (clippy) has anything to say about our code quality. Run the linter with cargo clippy:

flox [rust-env-demo] $ cargo clippy
...
Finished dev [unoptimized + debuginfo] target(s) in ...
Everything looks good. The maintainer of this project has included everything we need to lint our code.

Search & install missing dependencies

This project uses a just profile command to generate performance trace flamegraphs. However, the maintainer didn't include just in the environment:

flox [rust-env-demo] $ just profile
zsh: command not found: just

Let's search for it and install it to our Flox environment with flox search just:

flox [rust-env-demo] $ flox search just
just                                       A handy way to save and run project-specific commands
vscode-extensions.skellock.just            Provides syntax and recipe launcher for Just scripts
justify                                    Simple text alignment tool that supports left/right/center/fill justify alignment
...

We want that top search result. Let's install it with flox install just and run the just profile command.

flox [rust-env-demo] $ flox install just
✅ 'just' installed to environment rust-env-demo at /Users/myuser/rust-env-demo
flox [rust-env-demo] $ just profile
...
writing flamegraph to "flamegraph.svg"

It works!

Exit the environment

Now that we've worked on this project we can leave the Flox environment by typing exit and can see we no longer have access to packages we were just using:

flox [rust-env-demo] $ exit
$ which cargo
cargo not found

Where to next?