How to Use Flox: A Beginner's Guide

CodexFuse Team · 2026-11-01T13:21:00.000Z · 13 min read

What Is Flox, and What Does It Do?

Learning how to use Flox means learning how to build reproducible development environments without learning Nix. Flox is a free reproducible dev environment manager that gives every project its own declarative, version-pinned environment: the tools, libraries, environment variables, and services that project needs, defined in one file, so a project that works on your laptop works exactly the same on a teammate's machine and in CI. (One quick disambiguation, because search engines mix them up: this Flox is the developer environment manager — not Flox the antibiotic-family name that dominates generic search results.)

Under the hood, Flox uses Nix to deliver reproducibility — Flox's own phrasing is that it works "without requiring you to learn Nix." Flox's favorite analogy puts it in perspective: Flox is to Nix what early Linux distributions were to Linux. Instead of Nix's functional language, you write human-readable TOML. Say the boundary once: you never write a Nix expression, and isolation happens through pre-configured sub-shells, not containers.

That last line is the one that matters if you already know containers. A container packages an entire operating-system userland around your app; a Flox environment just layers the exact packages and variables onto the shell you already have. It is a lighter tool for a different job — which is why this guide pairs naturally with our Docker beginner guide rather than replacing it.

How Do You Use Flox? The 8-Step Quick Start

Here is the complete beginner arc. Everything below is detail on these eight steps.

1. Install Flox with the one-command installer (macOS, Linux, or WSL2).
2. Run flox init in your project folder to create a declarative .flox/ directory.
3. Search the catalog with flox search — Flox says its catalog indexes more than 190,000 distinct packages.
4. Install packages with flox install (this needs a free FloxHub account since October 20, 2026 — more below).
5. Activate the environment with flox activate so its packages and variables apply to your shell.
6. Edit the manifest with flox edit to pin versions, set environment variables, and add hooks.
7. Run background services with flox services — a database and a web server, for example.
8. Share it by committing .flox/ to git or pushing to FloxHub, then reproduce it in CI.

Installing Flox

Flox ships a one-command installer that detects your platform and installs the right package: a .pkg on macOS, a .deb on Debian and Ubuntu, or an .rpm on Fedora and RHEL, on both x86_64 and aarch64. On Windows, the supported path is WSL2 with an Ubuntu, Debian, or Oracle Linux 8.5 guest. The official install guide is the source of truth for the current command, so grab it from flox.dev/docs rather than trusting a copied one-liner from a blog.

One thing to know before you run it, said once: Flox bundles and manages its own Nix. Installing over an existing Nix setup replaces that Nix installation and rewrites /etc/nix/nix.conf, and that change is not revertible without reinstalling Nix yourself. If you already run Nix, that is the one consequence to weigh before clicking install.

Your First Environment: flox init

flox init creates a new Flox environment in your current directory. The direct answer to "what does it do": it creates a .flox/ directory holding the environment's declarative configuration — the manifest, the lock data, everything — and suggests the next steps: search for packages, install them, activate, and edit.

The .flox/ directory is the whole point of Flox, so treat it like source code: commit it to git. One committed directory is the entire environment definition, which means a teammate who clones the repo and runs flox activate gets the identical environment — the same package versions, the same variables, the same hooks. That commit is the moment a project stops being "works on my machine."

cd my-app
flox init
flox search nodejs
flox install nodejs
flox activate

Those four commands are the heart of every flox tutorial you will read, and they are the fastest way to feel what the tool does.

Finding and Installing Packages with flox search and flox install

flox search queries the Flox catalog — packages come with version listings so you can see what is available before you commit. flox install then adds the package to your environment's manifest. You can pin at install time: flox install nodejs@20 installs Node 20, and the manifest records the constraint rather than a one-off download.

Since October 20, 2026, said once: flox install, flox upgrade, and flox run — plus init, edit, and activate whenever they need to resolve the catalog — require a free FloxHub account. You sign in once with flox auth login using GitHub, Google, or GitLab. Reading stays public: flox search, flox show, and flox pull need no account, and activating an environment that is already locked needs no login either.

Pinning is where the reproducibility actually lives. Each package descriptor in the manifest can carry a version constraint (semver wildcards work), a systems list, and a priority — when two packages could provide the same binary, the lower priority number wins, with 5 as the default. Packages also ride stability cadences: unstable updates daily, staging weekly, stable monthly, and lts every six months; leave the cadence unset and you get the catalog's current default, which is unstable. If your environment must not drift, set an explicit version and an explicit cadence — that is the single highest-leverage line in any manifest.

One lane to draw here, once: if all you need is Python packages pinned, that is the job of a Python package manager, not an environment manager — see our uv beginner guide for that lane. Flox manages the whole environment around the code, including the system packages uv cannot touch.

The Activate Lesson: How flox activate Actually Works

flox activate is the command beginners misunderstand most, and the misunderstanding has one shape: packages do nothing until the environment is activated. Activation applies the environment's packages, variables, and hooks to a shell session. Flox gives you four invocation modes, and the differences matter, so say them once: the default opens an interactive sub-shell with the environment applied; flox activate -c CMD runs a command inside the environment; flox activate -- CMD execs the command directly and skips the [profile] section; and eval "$(flox activate)" applies the environment in place to your current shell instead of opening a sub-shell.

There is also an activation mode flag: -m (or --mode) takes dev or run. Run mode skips package-provided startup scripts — it is the leaner mode for executing a program rather than working in it. If you ever wonder why a hook ran for a teammate but not for you, check which mode you activated in.

Auto-activation is on by default, and it is the convenience most beginners end up loving: cd into a directory containing .flox and Flox prompts you to activate; cd out and the environment deactivates — and any services you started stop with it. Flox supports bash, fish, tcsh, and zsh, and your prompt shows which environments are active via the $FLOX_PROMPT variable.

The Manifest: One File, the Whole Environment

The flox manifest — manifest.toml — is where the environment is declared, and flox edit is the supported way to change it. The declarative lesson, in one sentence: every line in the manifest is a promise about the environment, and Flox turns those promises into a reproducible reality every time anyone activates it.

Top-level fields carry schema-version, minimum-cli-version, and a human description. Say the schema caution once: the manifest schema moves between releases — what you read here was verified against the current docs on November 1, 2026, so if a section name surprises you in a year, check the manifest reference before assuming a blog post is current.

[install]
hello.pkg-path = "hello"
nodejs.pkg-path = "nodejs"
nodejs.version = "^20"

[vars]
APP_ENV = "development"

[hook]
on-activate = '''
  echo "environment ready"
'''

[services]
db.command = "postgres -D data"

That small file declares an environment with two tools, a variable, an activation hook, and a database service. It is the kind of file that, committed to git, makes onboarding a new teammate a single flox activate.

Background Processes with flox services

The [services] section turns the environment from "a bag of tools" into "a running system." Each service declares a command plus optional vars, is-daemon, shutdown settings, depends-on ordering (wait for another service to start, complete, or succeed), systems, and auto-start.

Control is straightforward: flox activate -s (or --start-services) starts services with the environment, and flox services start, stop, restart, status, and logs manage them afterwards. Say the lifecycle rule once: services auto-stop when the last activation of the environment exits, and the default shutdown sends SIGTERM followed by SIGKILL. That auto-stop is why cd-ing out of a project folder with auto-activation cleanly tears down its database — a small detail that prevents a forest of forgotten Postgres instances.

Sharing Your Environment: git and FloxHub

Flox offers two sharing lanes. The first is the one you already own: commit .flox/ to git, and every clone of the repo carries the environment. If your project already lives on GitHub, the environment rides along in the same repository — see our GitHub beginner guide if the repo side of that is new to you.

The second lane is FloxHub, Flox's hosted environment registry. With a free FloxHub account you can flox push an environment, flox pull someone else's (use --copy to fork it into your own), and flox activate -r owner/name to run a remote environment without cloning anything. The [include] section goes further: it composes a remote environment into yours, so teams can publish a shared base environment and let projects layer their own packages on top. And environment generations give you rollback — if a package upgrade breaks something, you step back to the previous generation.

The Same Environment in CI

This is the reproducibility payoff, and it is the reason the whole arc ends here rather than at activation. Because the environment is declarative and locked — pinned packages, pinned cadences, a recorded CLI minimum — CI can activate the exact same environment your laptop uses. "Works on my machine" stops being a diagnosis because the machine is no longer a variable.

The practical habit: set minimum-cli-version in the manifest so CI runs against a known Flox version, and keep the lock data committed alongside the manifest. The same file that made your teammate's shell identical to yours makes the build runner's shell identical too.

Flox vs Nix vs Devbox vs Docker vs mise

Every one of these tools answers "my setup is a mess" differently. The table draws the lines once — the flox vs devbox question included — so pick the lane that matches your actual problem.

And the graduation line, said once: if you ever outgrow the abstraction and need the full expressiveness of the Nix language — custom derivations, overlays, the whole package — then Nix itself is the answer. Most teams never need to graduate; the teams that do will know, because they will hit the exact wall TOML cannot express.

7 Beginner Mistakes That Break Flox Environments

Sources

• Flox documentation home — the mental model and Linux-distribution analogy (flox.dev/docs, fetched 2026-11-01)
• Flox install guide — one-command installer, platform packages, WSL2 support, existing-Nix replacement (flox.dev/docs/install-flox/install, fetched 2026-11-01)
• Flox "Creating environments" tutorial — flox init, the .flox directory, catalog size figure (flox.dev/docs/tutorials/creating-environments, fetched 2026-11-01)
• flox-activate manual — the four invocation modes, dev/run modes, supported shells, auto-activation (flox.dev/docs/man/flox-activate, fetched 2026-11-01)
• Native auto-activation announcement (flox.dev/blog/auto-activation-is-now-native-in-flox, fetched 2026-11-01)
• manifest.toml reference — sections, install descriptors, stability cadences (flox.dev/docs/man/manifest.toml, fetched 2026-11-01)
• Services concepts guide — [services] fields, lifecycle, shutdown behavior (flox.dev/docs/concepts/services, fetched 2026-11-01)
• Sharing environments tutorial — git lane, FloxHub push/pull, remote activate, include, generations (flox.dev/docs/tutorials/sharing-environments, fetched 2026-11-01)
• Flox catalog login requirement announcement — October 20, 2026 account rule (flox.dev/blog/flox-catalog-login-requirement-what-you-need-to-know, fetched 2026-11-01)
• Flox changelog and v1.19.2 release notes via newreleases.io (flox.dev/docs/changelog, fetched 2026-11-01)
• Flox capital-markets case study — catalog "more than 190,000 distinct packages" figure (flox.dev PDF, fetched 2026-11-01)
• Community Flox cheatsheet — command quick reference (partrita.github.io, fetched 2026-11-01)

Frequently Asked Questions

Is Flox free to use?

Yes. Flox itself is free, and so is a FloxHub account. Since October 20, 2026, though, you need that free account — flox auth login via GitHub, Google, or GitLab — before flox install, flox upgrade, and flox run will work. Searching, showing, pulling, and activating an already-locked environment stay account-free.

Is Flox a replacement for Docker?

No, and that is a deliberate design choice, not a gap. Flox isolates environments through sub-shells rather than containers — it layers packages and variables onto your existing shell. Docker packages whole OS userlands as deployment artifacts. Many teams use both: Flox for the dev environment, Docker for shipping.

Do I need to know Nix to use Flox?

No. That is the entire premise: Flox uses Nix underneath for reproducibility but substitutes human-readable TOML for the Nix language, so you never write a Nix expression. If you later need the full power of Nix — custom derivations, overlays — Nix itself is the graduation path.

How is Flox different from Devbox?

Both are Nix-powered environment managers, so they solve the same problem with different frontends: Flox uses a TOML manifest with services, sharing via FloxHub, and environment generations for rollback, while Devbox uses JSON configuration. The practical difference is workflow preference and the surrounding ecosystem — try both on one project and keep the one whose commands you remember.

Can I use Flox on Windows?

The supported path is WSL2 with an Ubuntu, Debian, or Oracle Linux 8.5 guest — Flox's installer targets those distributions on both x86_64 and aarch64. Native Windows support is not the documented route.