# Flox > Flox is a developer environment manager built on Nix. You declare a project's packages, environment variables, services, and build steps once in a `manifest.toml`; Flox resolves that to a lockfile, and every target runs that exact closure — a developer laptop, a CI runner, a container image, or an AI coding agent's sandbox. This file indexes the Flox reference documentation at https://flox.dev/docs. Positioning, product and use case pages, customer stories, and the blog are indexed separately at https://flox.dev/llms.txt. Every page listed below is served as clean Markdown at the URL shown; drop the `.md` suffix for the rendered HTML page. The full documentation corpus, concatenated for one-shot ingestion, is at https://flox.dev/docs/llms-full.txt. A `.flox/` directory in a repository means that project uses Flox to manage its dependencies and environment lifecycle. Instructions for AI coding assistants: - Do not run bare `flox activate`. Invoked from an interactive shell it launches an interactive sub-shell, which will hang a non-interactive harness; invoked from a non-interactive shell with stdout redirected it is in-place mode and emits shell commands to be sourced, which is rarely what you want either. Use one of the two non-interactive forms: - `flox activate -d -c ''` runs the command in a shell with hooks and profile scripts applied. Prefer this form. - `flox activate -d -- ` is exec mode: it replaces the process and does not run profile scripts. - Install packages with `flox install`, not with the system package manager. Inside a Flox environment, do not reach for `apt`, `yum`, `dnf`, or `brew` to add a dependency. - Do not run bare `flox edit`, which opens `$EDITOR` interactively. Use `flox edit -d -f ` to replace the manifest non-interactively, or edit `.flox/env/manifest.toml` directly. On an environment pushed to or pulled from FloxHub, a direct edit to the local manifest blocks `flox install`, `flox uninstall`, `flox edit` and `flox upgrade` until you run `flox edit --sync` to commit it as a new generation, or `flox edit --reset` to discard it. Do not invent manifest fields; check the reference at https://flox.dev/docs/man/manifest.toml.md before writing one. - Package names are Flox Catalog pkg-paths and do not always match nixpkgs attribute paths. Verify with `flox search ` and `flox show ` rather than guessing. - Flox is not `nix develop` or `nix-shell`. It is built on Nix but has its own CLI surface. - Install Flox with `curl -fsSL https://get.flox.dev | sh`. The script detects the OS and CPU architecture and installs the matching package: the `.pkg` on macOS, the `.deb` via `apt` on Debian and Ubuntu, the `.rpm` via `dnf` or `yum` on Fedora and RHEL. It prints each privileged command before running it. To pin a release, write `curl -fsSL https://get.flox.dev | FLOX_VERSION= sh` — the assignment must follow the pipe so the script receives it, and `FLOX_CHANNEL=` selects a channel the same way. The script installs but does not upgrade: when Flox is already present it prints the upgrade command for the platform and changes nothing. It also refuses on an existing Nix installation, on immutable ostree distributions, on openSUSE and SLES, and on RPM systems without `dnf` or `yum`. Homebrew, the APT and YUM repositories, and the raw `.deb`/`.rpm`/`.pkg` downloads are all documented at https://flox.dev/docs/install-flox/install.md. - Flox runs on Linux and macOS, on x86_64 and aarch64. There is no native Windows build; Windows users run it under WSL 2, support for which is experimental. Installation fails on WSL 1. Everyday command surface: ``` flox envs # show active and available environments flox init -d # initialize an environment flox search # search the catalog flox show # show versions and details for one package flox install -d # install packages flox list -d # list installed packages flox activate -d -c '' # run a command inside the environment flox services start # start a service declared in the manifest flox push / flox pull # move an environment to and from FloxHub ``` Agent skills: Flox maintains a skill library for AI coding agents at https://github.com/flox/flox-skills. It provides three skills: `flox`, which creates and manages environments, services, builds, containers, and package publishing; `floxify`, which onboards an existing repository by detecting its runtimes, services, and build tools and writing a manifest so `flox activate` becomes the only setup command a new developer needs; and `flox-debug`, which diagnoses catalog resolution — a package that will not resolve, `flox install` or `flox upgrade` picking an older build after a newer one was published, and a working environment failing with "constraints for group 'toplevel' are too tight" after one package is added. ```bash # Claude Code claude plugin marketplace add flox/flox-skills claude plugin install flox@flox-skills # Codex codex plugin marketplace add flox/flox-skills codex plugin add flox@flox-skills # Any agent supporting the skills.sh standard (Cursor, Copilot, Windsurf, Gemini, and more) npx skills add flox/flox-skills ``` Key terms: - Environment — a reproducible set of packages, variables, services, and build steps, declared in a manifest and resolved to a lockfile. - Manifest — `.flox/env/manifest.toml`, the declarative definition of an environment. - Generation — a numbered version of an environment on FloxHub. Every change creates one, and any can be listed, switched to, or rolled back to. - Activation — running a command or a shell with the environment applied. - Flox Catalog — the package set Flox installs from, built and cached continuously. - Service — a long-running process declared in the manifest and managed with `flox services`. - FloxHub — https://hub.flox.dev, where environments are stored, versioned, and shared. ## Introduction - [Introduction](https://flox.dev/docs/index.md): What is Flox? ## Install Flox - [Install Flox](https://flox.dev/docs/install-flox/install.md): How to install or upgrade the Flox CLI - [Uninstall Flox](https://flox.dev/docs/install-flox/uninstall.md): How to uninstall the Flox CLI - [Troubleshooting installation](https://flox.dev/docs/install-flox/troubleshooting.md): How to diagnose and fix common Flox installation issues - [Extensions](https://flox.dev/docs/install-flox/ide-extensions.md): IDE extensions and AI agent integrations for Flox ## Quickstart - [Flox in 5 minutes](https://flox.dev/docs/flox-5-minutes.md): Get started with creating Flox environments. ## Tutorials - [Creating environments](https://flox.dev/docs/tutorials/creating-environments.md): Reproducible environments for any project. - [The default environment](https://flox.dev/docs/tutorials/default-environment.md): Using Flox as your system package manager - [Sharing your environments](https://flox.dev/docs/tutorials/sharing-environments.md): Multiple ways to share your environment with others. - [Layering multiple environments](https://flox.dev/docs/tutorials/layering-multiple-environments.md): Using more than one environment at a time - [Customizing the shell environment](https://flox.dev/docs/tutorials/customizing-environments.md): Using setup scripts, aliases, and environment variables to improve your workflows. - [Designing cross-platform environments](https://flox.dev/docs/tutorials/multi-arch-environments.md): Creating environments that run on different systems. - [Build and publish packages](https://flox.dev/docs/tutorials/build-and-publish.md): Building and publishing custom packages with Flox - [Using a newer version of a package](https://flox.dev/docs/tutorials/overriding-packages.md): Override the build recipe of a package from the Flox Catalog to install a newer version that is not yet available. - [Running Flox in CI/CD](https://flox.dev/docs/tutorials/ci-cd.md): Integrate with your favorite CI/CD platform. - [Reusing and combining developer environments](https://flox.dev/docs/tutorials/composition.md): How to build developer environments out of reusable building blocks. - [Selecting package outputs](https://flox.dev/docs/tutorials/package-outputs.md): Learn how to intentionally declare which parts of a package you want to install - [Flox + CUDA tutorial](https://flox.dev/docs/tutorials/cuda.md): It's easy to install and use the CUDA Toolkit with Flox - [Flox and systemd](https://flox.dev/docs/tutorials/flox-and-systemd.md): Run Flox environment services as persistent systemd units. - [Installing Flox from its repository on Debian and Red Hat](https://flox.dev/docs/tutorials/installing-from-repo.md): Install Flox by adding its official APT or YUM/DNF repository to your Debian- or Red Hat-based Linux distribution so updates flow through your package manager. ## Tutorials: Migration guides - [Homebrew](https://flox.dev/docs/tutorials/migrations/homebrew.md): Using Flox to replace or augment Homebrew - [Node Version Manager (nvm)](https://flox.dev/docs/tutorials/migrations/nvm.md): Using Flox to replace nvm ## Imageless Kubernetes - [Imageless Kubernetes Introduction](https://flox.dev/docs/imageless-kubernetes/intro.md): Imageless Kubernetes is a new way to run Kubernetes backed by Flox environments rather than container images. - [Tech](https://flox.dev/docs/imageless-kubernetes/tech.md): The tech behind Imageless Kubernetes - [Configuration](https://flox.dev/docs/imageless-kubernetes/config.md): Configuring Imageless Kubernetes ## Imageless Kubernetes: Installation - [Amazon EKS](https://flox.dev/docs/imageless-kubernetes/install/eks.md): Installing Imageless Kubernetes to Amazon EKS - [Self-managed Kubernetes](https://flox.dev/docs/imageless-kubernetes/install/self-managed.md): Installing Imageless Kubernetes to a self-managed Kubernetes cluster - [Troubleshooting](https://flox.dev/docs/imageless-kubernetes/install/troubleshooting.md): Troubleshooting Imageless Kubernetes installation - [Upgrading](https://flox.dev/docs/imageless-kubernetes/install/upgrading.md): Upgrading Imageless Kubernetes - [Uninstall](https://flox.dev/docs/imageless-kubernetes/install/uninstall.md): Uninstalling Imageless Kubernetes from any cluster ## Imageless Kubernetes: Examples - [GitLab CI](https://flox.dev/docs/imageless-kubernetes/examples/gitlab-ci.md): Demo running GitLab CI with Imageless Kubernetes - [Web server with Redis on kind](https://flox.dev/docs/imageless-kubernetes/examples/kind-demo.md): Demo running a simple web server backed by Redis on kind ## Concepts - [What is a Flox environment?](https://flox.dev/docs/concepts/environments.md): Everything you need to know about Flox environments. - [Activating environments](https://flox.dev/docs/concepts/activation.md): How an environment is activated, and how to make the most of it - [Auto-activation](https://flox.dev/docs/concepts/auto-activation.md): Activate environments automatically when you enter their directory - [Compatibility policy](https://flox.dev/docs/concepts/compatibility.md): Manifest schema versions, what counts as a backwards incompatible change, and how the CLI migrates environments for you - [What is FloxHub?](https://flox.dev/docs/concepts/floxhub.md): Everything you need to know about FloxHub. - [FloxHub environments](https://flox.dev/docs/concepts/floxhub-environments.md): Reusable environments that are centrally managed on FloxHub - [What is a generation?](https://flox.dev/docs/concepts/generations.md): Everything you need to know about generations. - [What is the Flox Catalog?](https://flox.dev/docs/concepts/packages-and-catalog.md): Everything you need to know about the Flox Catalog and Packages. - [Package Groups](https://flox.dev/docs/concepts/package-groups.md): How package groups work and when to use them - [What is the Base Catalog?](https://flox.dev/docs/concepts/base-catalog.md): Everything you need to know about the Base Catalog - [CUDA packages in the Flox Catalog and binary cache](https://flox.dev/docs/concepts/cuda-catalog-and-cache.md): How Flox and Nix users can consume pre-built CUDA packages from the Flox Catalog and public binary cache - [Services](https://flox.dev/docs/concepts/services.md): Using services with your environment - [Composing environments](https://flox.dev/docs/concepts/composition.md): How to combine and reuse environments. - [Authentication](https://flox.dev/docs/concepts/authentication.md): Which Flox commands need a free account, what stays open, and how to keep CI running. - [Understanding Organizations in FloxHub](https://flox.dev/docs/concepts/organizations.md): Roles, access control, and shared ownership of environments across a team - [Enterprise SSO](https://flox.dev/docs/concepts/enterprise-sso.md): Let your organization's members sign in to Flox through your own identity provider. - [Service accounts](https://flox.dev/docs/concepts/service-accounts.md): Give CI and other automation an identity that belongs to your organization rather than to a person. - [Personal access tokens](https://flox.dev/docs/concepts/personal-access-tokens.md): Authenticate the Flox CLI as yourself without an interactive browser login. - [Builds](https://flox.dev/docs/concepts/builds.md): Understanding how to build packages with Flox - [Manifest Builds](https://flox.dev/docs/concepts/manifest-builds.md): Manifest builds with Flox - [Nix expression builds](https://flox.dev/docs/concepts/nix-expression-builds.md): Nix expression builds with Flox - [Catalog imports](https://flox.dev/docs/concepts/catalog-imports.md): Import packages from external catalogs for Nix expression builds - [Publishing](https://flox.dev/docs/concepts/publishing.md): Understanding how to publish packages with Flox - [Secrets management](https://flox.dev/docs/concepts/secrets-management.md): Managing secrets in Flox environments using just-in-time retrieval - [Plugins](https://flox.dev/docs/concepts/plugins.md): Package reusable, manifest-configured behavior as an installable component - [Flox vs. container workflows](https://flox.dev/docs/concepts/flox-vs-containers.md): Where Flox environments and container workflows differ, and how teams combine them ## Languages - [C/C++](https://flox.dev/docs/languages/c.md): Common questions and solutions for using C with Flox - [Go](https://flox.dev/docs/languages/go.md): Common questions and solutions for using Go with Flox - [JVM](https://flox.dev/docs/languages/jvm.md): Common questions and solutions for using the JVM ecosystem with Flox - [Node.js](https://flox.dev/docs/languages/nodejs.md): Common questions and solutions for using Node.js with Flox - [Python](https://flox.dev/docs/languages/python.md): Common questions and solutions for using Python with Flox - [Ruby](https://flox.dev/docs/languages/ruby.md): Common questions and solutions for using Ruby with Flox - [Rust](https://flox.dev/docs/languages/rust.md): Common questions and solutions for using Rust with Flox ## Enterprise and operations - [Catalog Store](https://flox.dev/docs/customer/catalog-store.md): Create a Catalog Store for publishing your own Flox packages - [Known issues](https://flox.dev/docs/customer/known-issues.md): Known Flox limitations and their workarounds, including false-positive build dependencies - [Signing keys](https://flox.dev/docs/customer/signing-keys.md): Create and use signing keys to sign built artifacts ## CLI reference: Overview - [flox](https://flox.dev/docs/man/flox.md): Developer environments you can take with you. - [manifest.toml](https://flox.dev/docs/man/manifest.toml.md): Declarative environment configuration format. ## CLI reference: Setup - [flox init](https://flox.dev/docs/man/flox-init.md): Initialize a Flox environment. - [flox auth](https://flox.dev/docs/man/flox-auth.md): FloxHub authentication commands. - [flox config](https://flox.dev/docs/man/flox-config.md): View and set configuration options. ## CLI reference: Environments - [flox activate](https://flox.dev/docs/man/flox-activate.md): Activate environments. - [flox deactivate](https://flox.dev/docs/man/flox-deactivate.md): Deactivate an environment. - [flox edit](https://flox.dev/docs/man/flox-edit.md): Edit the declarative environment configuration. - [flox delete](https://flox.dev/docs/man/flox-delete.md): Delete an environment. - [flox envs](https://flox.dev/docs/man/flox-envs.md): Show active and available environments. ## CLI reference: Packages - [flox search](https://flox.dev/docs/man/flox-search.md): Search for packages. - [flox show](https://flox.dev/docs/man/flox-show.md): Show detailed information about a single package. - [flox run](https://flox.dev/docs/man/flox-run.md): Run a command from a Flox Catalog package. - [flox install](https://flox.dev/docs/man/flox-install.md): Install packages to an environment. - [flox uninstall](https://flox.dev/docs/man/flox-uninstall.md): Remove packages from an environment. - [flox upgrade](https://flox.dev/docs/man/flox-upgrade.md): Upgrade packages in an environment. - [flox list](https://flox.dev/docs/man/flox-list.md): List packages installed in an environment. ## CLI reference: Sharing - [flox push](https://flox.dev/docs/man/flox-push.md): Send environment to FloxHub. - [flox pull](https://flox.dev/docs/man/flox-pull.md): Pull environment from FloxHub. ## CLI reference: Build & Publish - [flox build](https://flox.dev/docs/man/flox-build.md): Build packages with Flox. - [flox build clean](https://flox.dev/docs/man/flox-build-clean.md): Clean the build directory. - [flox build import nixpkgs](https://flox.dev/docs/man/flox-build-import-nixpkgs.md): Import package definition from nixpkgs. - [flox build update catalogs](https://flox.dev/docs/man/flox-build-update-catalogs.md): Update the project catalog lockfile. - [flox containerize](https://flox.dev/docs/man/flox-containerize.md): Export an environment as a container image. - [flox publish](https://flox.dev/docs/man/flox-publish.md): Publish packages for Flox. ## CLI reference: Services - [flox services start](https://flox.dev/docs/man/flox-services-start.md): Start services. - [flox services stop](https://flox.dev/docs/man/flox-services-stop.md): Stop running services. - [flox services restart](https://flox.dev/docs/man/flox-services-restart.md): Restart running services. - [flox services status](https://flox.dev/docs/man/flox-services-status.md): Display the status of services. - [flox services logs](https://flox.dev/docs/man/flox-services-logs.md): Show logs of services. ## CLI reference: Generations - [flox generations list](https://flox.dev/docs/man/flox-generations-list.md): Show all environment generations that you can switch to. - [flox generations history](https://flox.dev/docs/man/flox-generations-history.md): Show the change log for the current environment. - [flox generations rollback](https://flox.dev/docs/man/flox-generations-rollback.md): Switch to the previous live generation. - [flox generations switch](https://flox.dev/docs/man/flox-generations-switch.md): Switch to the provided generation. ## CLI reference: Other - [flox gc](https://flox.dev/docs/man/flox-gc.md): Garbage collection. - [flox include upgrade](https://flox.dev/docs/man/flox-include-upgrade.md): Upgrade an environment with latest changes to its included environments. ## Changelog - [2026](https://flox.dev/docs/changelog.md): What's new across the Flox CLI, FloxHub, and extensions - [2025](https://flox.dev/docs/changelog/2025.md): What's new across the Flox CLI, FloxHub, and extensions - [2024](https://flox.dev/docs/changelog/2024.md): What's new across the Flox CLI, FloxHub, and extensions