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:

​
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:
With all the dependencies installed, you can confirm everything is working by running the sample Go project:
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:
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:
To check available versions of a package, use flox show:
To install a package, run:

​
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:
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:
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:
You can check on the status of services and tail their logs just like you would with any process manager:
Press Ctrl-C to stop watching the logs. When you’re done, stop the service:
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.