Flox in 5 minutes
Flox is a next-generation, language-agnostic package and environment manager. With it you create sets of tools, environment variables, and setup scripts that work reproducibly from machine to machine, x86_64 to Arm, and macOS to Linux. The best part is that all of this works without causing version conflicts between projects.
We call these stacks Flox environments. Flox environments are based on carefully configured subshells, so there's no container isolation preventing you from using your favorite tools or artisanally handcrafted dotfiles. Even better, these environments compose and layer so you can prepare different environments for different needs and combine them to seamlessly work across different contexts.
Finally, you can use Flox environments for local development, CI, and production to ensure that you have a consistent set of software across the entire software development lifecycle.
Buckle up, it's time for a whirlwind tour of Flox.
Get the project
We've prepared a sample project for you, but you'll need to install Flox to follow along. Once you have Flox, you can clone the project:
Tools prepared for you
Once you have the project, you can run the flox activate command to enter the environment:
$ flox activate
✅ You are now using the environment 'flox-in-5min'.
To stop using this environment, type 'exit'
You now have all of the dependencies needed to follow along. To prove it, run the following command:
Whoever prepared this environment knew that you needed a Go toolchain in order to work on the project, so they included a Go toolchain in the Flox environment. This is the magic of Flox.
To get to work on an existing project you need two commands: git clone and flox activate.
Onboarding a new engineer now has one step: install Flox.
No more README.md with a list of libraries you need install.
No more setup.sh.
Time not spent installing tools and solving dependency conflicts is time spent getting to know the team and the project.
Now let's see what else is installed to the environment with the flox list command:
$ flox list
bun: bun (1.2.20)
coreutils: coreutils (9.7)
go: go (1.24.5)
nasm: nasm (2.16.03)
nodejs_24: nodejs_24 (24.5.0)
That's right, not only do you have Go installed, you also have a cutting edge Javascript toolchain with Bun.
Since Flox is language agnostic, you can use one tool (Flox) to manage your entire stack of developer tools.
This environment covers the full stack, from a Zig-powered Javascript bundler and runtime at the top of the stack, to an assembler like nasm at the very bottom of the stack.
This environment is also reproducible, meaning that anyone that runs flox activate will get exactly the same set of tools, and that's super important!
You'd think that something as simple as the sleep command wouldn't cause problems, but /bin/sleep infinity will sleep for a surprisingly short time on macOS (ask us how we know).
Ensuring that everyone is using the exact same packages prevents wasted time and subtle bugs.
Finding packages
Let's say we want a new package: ripgrep.
$ flox search ripgrep
ripgrep Utility that combines the usability of The Silver Searcher with the raw speed of grep
ripgrep-all Ripgrep, but also search in PDFs, E-Books, Office documents, zip, tar.gz, and more
emacsPackages.ripgrep <no description provided>
vimPlugins.blink-ripgrep-nvim <no description provided>
emacsPackages.projectile-ripgrep <no description provided>
vgrep User-friendly pager for grep/git-grep/ripgrep
repgrep Interactive replacer for ripgrep that makes it easy to find and replace across files on the command line
grip-grab Fast, more lightweight ripgrep alternative for daily use cases
bat-extras.batgrep Quickly search through and highlight files using ripgrep
Use 'flox show <package>' to see available versions
Cool, what if I want a specific version?
$ flox show ripgrep
ripgrep - Utility that combines the usability of The Silver Searcher with the raw speed of grep
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected] (aarch64-linux, x86_64-darwin, x86_64-linux only)
To install it you would run
What else can Flox do?
Your environment is stored as a .flox directory in your repository, but you can also push it to FloxHub to make it centrally managed and available from anywhere.
We only have 5 minutes, so we're going to skip over that for now, but see the sharing environments tutorial for more information.
The configuration for your environment is called the "manifest", a TOML file stored at .flox/env/manifest.toml.
You can print it with flox list -c or edit it with flox edit.
Let's take a look at this manifest:
version = 1
[install]
go.pkg-path = "go"
nodejs_24.pkg-path = "nodejs_24"
ripgrep.pkg-path = "ripgrep"
coreutils.pkg-path = "coreutils"
bun.pkg-path = "bun"
nasm.pkg-path = "nasm"
[vars]
MY_VAR = "pretty neat"
[services.stopwatch]
command = '''
while true; do date; sleep 5; done
'''
Pretty straightforward.
Packages go in [install], and maybe the syntax is a little funky, but that's for a good reason we don't have time to get into.
See this page for more details about the various things you can specify about a package.
What are these [vars] and [services] sections?
The [vars] section defines environment variables you want set in your shell after running flox activate.
See for yourself:
Imagine using this to set a port number or some other configuration value.
The [services] section is how you define background processes for your environment, like a web server or a database.
Start the stopwatch service with the flox services start command:
Let's make sure it's running:
Now let's see its logs:
$ flox services logs --follow
stopwatch: Fri Aug 22 19:17:30 MDT 2025
stopwatch: Fri Aug 22 19:17:35 MDT 2025
stopwatch: Fri Aug 22 19:17:40 MDT 2025
stopwatch: Fri Aug 22 19:17:45 MDT 2025
stopwatch: Fri Aug 22 19:17:50 MDT 2025
stopwatch: Fri Aug 22 19:17:55 MDT 2025
stopwatch: Fri Aug 22 19:18:00 MDT 2025
stopwatch: Fri Aug 22 19:18:05 MDT 2025
This service prints the current time every 5 seconds, which you can see defined in the services.stopwatch.command field of the manifest.
Press Ctrl-C to stop watching the logs, unless you really enjoy that for some reason.
We don't want the service to run forever, so let's stop it with the flox services stop command.
A really cool feature of Flox is that if you were to exit the environment by running exit or pressing Ctrl-D, the services running in the environment would be automatically stopped.
This feature has given our engineers gray hair, but we think the dopamine hit is worth it.
If you want services to start when you enter the environment, you can use the -s/--start-services option when running flox activate.
Customizing your shell
To wrap things up, let's say you want to set some project-specific aliases.
Run flox edit and add this to the bottom of your manifest:
[profile]
bash = '''
alias sayhi="echo 'Hello there, bash user'"
'''
zsh = '''
alias sayhi="echo 'Hello there, zsh user'"
'''
# The superior shell
fish = '''
alias sayhi "echo 'Hello there, fish user'"
'''
# Hello from 1989
tcsh = '''
alias sayhi "echo 'Hello there, tcsh user'"
'''
Now if you exit the Flox environment via Ctrl-D or exit and reactivate via flox activate, you'll have a wonderful new shell alias called sayhi:
There is a wealth of ways that you can customize the shell environment inside of your Flox environment. See the customizing the shell enviroment tutorial for more information.
But wait, there's more!
This probably took longer than 5 minutes, but hopefully changing the way you develop software was worth it. There are so many things we didn't have time to cover, so here's some additional reading material to keep you busy: