Skip to main content
“What should go in my default environment?” is one of the most common questions about Flox. The answer depends on how you work, so this page walks through four example manifests. Each one uses a different part of the manifest, so you can mix and match the pieces you need. If you haven’t set up a default environment yet, start with the default environment tutorial.

​
What belongs in a default environment

Your default environment is active in every shell, in every directory. That makes it the right home for tools you use everywhere:
  • General-purpose command-line tools, such as git, curl, and jq
  • Your editor (Neovim, Helix), terminal multiplexer (tmux, Zellij), and shell prompt (Starship, Oh My Posh)
  • Coding agents, such as Claude Code and Codex
  • CLIs for cloud providers and other services you use across projects, such as awscli2, azure-cli, and gh
Some tools belong in a project’s environment instead:
  • Language toolchains pinned to a project, such as Node.js 20 for one repository and Node.js 22 for another
  • Services, such as databases and message queues
  • Libraries and build dependencies that a project needs to compile
A useful rule: if a project needs a tool to build, test, or run, put the tool in that project’s environment. Your default environment is personal, so your teammates and CI jobs don’t have it. When you layer a project environment on top of your default environment, the project’s packages take precedence. Keep your default environment quick to activate, too. It activates every time you open a shell, so avoid slow commands and network calls in its [hook] and [profile] scripts.

​
Try an example

Open your default environment’s manifest in your editor:
Copy in the sections you want from an example, then save and close the file. Flox validates the manifest when you save it. Then push the change to FloxHub so your other machines can pull it:
Each push creates a new generation, so you can experiment freely. If you change your mind, roll back with flox generations rollback.

​
Everyday essentials

Start here if you’re replacing Homebrew, apt, or another system package manager. This environment is just a list of packages, so you can build it without opening the manifest at all:
Here’s the manifest, with a description that explains what the environment is for:
manifest.toml
If you’re moving from Homebrew, the Homebrew migration guide shows how to list the formulae you installed with brew leaves and find each one in the catalog. Catalog package names usually match Homebrew’s, but not always, so use flox search to check.

​
Shell power user

This environment takes your editor, prompt, and shell integrations to every machine, so you don’t have to copy dotfiles around.
manifest.toml
  • [vars] sets EDITOR and VISUAL in every shell, so tools such as git open Neovim.
  • [profile] has one script per shell. Your shell runs only the script that matches it, so the same environment works in Bash, Zsh, and Fish. If you use tcsh, add a tcsh script the same way.
  • The scripts set up the Starship prompt, the z command from zoxide for jumping between directories, and the fzf key bindings. They also alias ls to eza.
Profile scripts run every time a shell starts, so keep them to quick setup like this. See [profile] for details.
If you already set up these tools in .bashrc, .zshrc, or config.fish, remove those lines after you move them into the manifest, so the setup doesn’t run twice.

​
macOS and Linux

If you work on a Mac but deploy to Linux, or split your time between both, one default environment can serve all of your machines. Use a package’s systems option to install it only where you need it.
manifest.toml
  • By default, an environment supports aarch64-darwin, aarch64-linux, and x86_64-linux, so it works on Apple silicon Macs and on ARM and x86 Linux.
  • A package’s systems option limits that package to some of those systems. Here, the GNU tools install only on macOS, and Linux-only tools such as strace install only on Linux. Without it, Flox can’t resolve the environment on systems where the package isn’t available.
Your default environment’s packages come before the system’s in your PATH, so GNU sed, grep, find, and tar replace the BSD versions that ship with macOS. If your scripts rely on BSD behavior, such as sed -i '', leave these packages out.

​
Team baseline

If your team uses FloxHub organizations, you can publish a shared baseline environment with internal CLIs and approved tool versions. Everyone on the team can then include it in their own default environment and add personal tools on top.
manifest.toml
  • Flox merges the baseline into your environment. Your own manifest takes priority, so you can add packages or override the version of a baseline package without changing the baseline for everyone else. You can’t remove a package that the baseline installs.
  • Include the baseline with remote, not dir. Your default environment lives on FloxHub, and you can’t push an environment that includes a local directory.
  • To see the merged manifest, run flox list -D --config.
Changes to the baseline don’t reach you automatically. When you’re ready for the latest version, pull it in and push the result:
To build the baseline itself, see reusing and combining developer environments. For how merging works, see composing environments.

​
Where to next