> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Flox in 5 minutes

> Get started with creating Flox environments.

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](/index).

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](/install-flox/install) to follow along.
Once you have Flox, you can clone the project:

```bash theme={null}
git clone https://github.com/flox/flox-in-5min.git
```

```bash theme={null}
cd flox-in-5min
```

## Activate and explore

Run [`flox activate`](/man/flox-activate) to enter the environment. This will make all of the packages defined in the environment available in your shell:

```console theme={null}
$ 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:

```console theme={null}
$ 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`](/man/flox-list) command:

```console theme={null}
$ 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](https://bun.sh/), 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`:

```console theme={null}
$ 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`:

```console theme={null}
$ 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:

```bash theme={null}
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](https://hub.flox.dev).
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](https://hub.flox.dev/signup). Then authenticate with the CLI:

```bash theme={null}
flox auth login
```

This will open your browser and ask you to confirm the device code displayed in your terminal:

<img src="https://mintcdn.com/flox/TGd54292LI04fuY9/images/device-confirmation.png?fit=max&auto=format&n=TGd54292LI04fuY9&q=85&s=bda87bd4be890ff2e222852cd15e6e40" alt="FloxHub device confirmation" width="1800" height="1750" data-path="images/device-confirmation.png" />

Push your environment to FloxHub:

```bash theme={null}
flox push
```

Once the push is complete, you'll see a confirmation along with commands others can use to access your environment:

<img src="https://mintcdn.com/flox/TGd54292LI04fuY9/images/auth-successfull.png?fit=max&auto=format&n=TGd54292LI04fuY9&q=85&s=ce7c9763d6d5273705efb006f4fddb12" alt="Successful push to FloxHub" width="1516" height="306" data-path="images/auth-successfull.png" />

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:

<img src="https://mintcdn.com/flox/TGd54292LI04fuY9/images/floxhub-environment.png?fit=max&auto=format&n=TGd54292LI04fuY9&q=85&s=0586ee7a4a2ad17f39106d9cd31f03d0" alt="FloxHub environment view" width="1079" height="1031" data-path="images/floxhub-environment.png" />

## 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:

```console theme={null}
$ 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:

```console theme={null}
$ flox services status
NAME       STATUS       PID
stopwatch  Running    51774
```

```console theme={null}
$ 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:

```console theme={null}
$ 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:

* [Customize your shell environment](/tutorials/customizing-environments) with aliases, scripts, and hooks
* [Design cross platform environments](/tutorials/multi-arch-environments) that work on both macOS and Linux
* [Reuse and combine environments](/tutorials/composition) to build modular developer toolchains
* [Run Flox in CI](/tutorials/ci-cd) for consistent builds across your pipeline
* [Build and publish packages with Flox](/tutorials/build-and-publish)

Have questions? Reach out on [Slack](https://go.flox.dev/slack) or [Discourse](https://discourse.flox.dev).