Skip to main content
Flox is a language agnostic package and environment manager that lets you create reproducible environments that work across machines, architectures, and operating systems. It supports macOS and Linux on both x86_64 and ARM architectures, so your team can share a single environment definition regardless of what hardware they’re on. To learn more about what Flox is and what it can do, see the Introduction. In this guide you’ll use a sample project to create a Flox environment, install packages, set environment variables, run services, and customize your shell. Buckle up, it’s time for a whirlwind tour of Flox.

​
Clone the sample 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: 
git clone https://github.com/flox/flox-in-5min.git

cd flox-in-5min

​
Activate and explore

Run flox activate to enter the environment. This will make all of the packages defined in the environment available in your shell: 
$ flox activate
✔ You are now using the environment 'flox-in-5min'.
To stop using this environment, type 'exit'
With all the dependencies installed, you can confirm everything is working by running the sample Go project: 
$ go run main.go
Hello from Flox!
You didn’t have to install Go yourself. The environment already had it defined, so flox activate made it available automatically. To get started on any project with Flox, all you need is git clone and flox activate. 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)
This environment includes tools across multiple languages, from Go to Node.js to Bun, all the way down to an assembler like nasm. Flox is language agnostic, so you can manage your entire stack of developer tools in one place. Anyone who runs flox activate on this project will get the exact same set of packages.

​
Managing packages

Flox makes it easy to search for, inspect, and install packages from the Flox Catalog. Use flox search to find packages. For example, to search for 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
To check available versions of a package, use flox show: 
$ flox show ripgrep
ripgrep - Utility that combines the usability of The Silver Searcher with the raw speed of grep
    ripgrep@14.1.1
    ripgrep@14.1.0
    ripgrep@14.0.3
    ripgrep@14.0.1
    ripgrep@13.0.0
    ripgrep@12.1.1 (aarch64-linux, x86_64-darwin, x86_64-linux only)
To install a package, run: 
flox install ripgrep

​
Push to FloxHub

Now that you’ve made changes to the environment, share it with your team by pushing it to FloxHub. FloxHub is a platform for sharing and discovering Flox environments and packages, making it easy for your team to stay in sync. If you haven’t already, sign up for a FloxHub account. Then authenticate with the CLI: 
flox auth login
This will open your browser and ask you to confirm the device code displayed in your terminal: FloxHub device confirmation Push your environment to FloxHub: 
flox push
Once the push is complete, you’ll see a confirmation along with commands others can use to access your environment: Successful push to FloxHub You can view your environment’s manifest, packages, environment variables, and services in the FloxHub web interface. This gives your team a quick way to see what’s in an environment before pulling it, track changes across generations, and check supported platforms: FloxHub environment view

​
Services

Most projects need more than just packages. You might need a web server, a database, or a background worker running alongside your code. Flox handles this through the [services] section of the manifest. The sample environment includes a simple stopwatch service. Start it up: 
$ flox services start
✔ Service 'stopwatch' started.
You can check on the status of services and tail their logs just like you would with any process manager: 
$ flox services status
NAME       STATUS       PID
stopwatch  Running    51774

$ 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
Press Ctrl-C to stop watching the logs. When you’re done, stop the service: 
$ flox services stop
✔ Service 'stopwatch' stopped
Services are automatically stopped when you exit the environment, so you don’t have to worry about orphaned processes. If you want services to start automatically when you activate the environment, use flox activate -s.

​
What’s next?

You’ve created an environment, installed packages, pushed to FloxHub, and ran services. Here are some next steps to keep going: Have questions? Reach out on Slack or Discourse.