Lesson 6: Sharing Environments

Make your setups portable and shareable with your team

Learning Objectives

Understand how to make flakes portable and shareable
Manage dependencies for your team
Handle platform differences (macOS, Linux)
Document your environment requirements
Version control best practices for Nix projects

The Power of Shared Flakes

A flake + flake.lock in git means anyone can get the exact same environment with one command:

git clone https://github.com/user/my-project.git
cd my-project
nix develop

No installation instructions, no "Works on my machine". Perfect reproducibility.

Making Flakes Shareable

1. Pin Versions Explicitly

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
  # ↑ Use a stable release, not 'unstable'
};

2. Document Your Requirements

Add comments to your flake.nix so teammates understand:

inputs = {
  # Stable nixpkgs from November 2023
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";

  # Build utilities helper
  flake-utils.url = "github:numtide/flake-utils";
};

3. Support Multiple Platforms

flake-utils.lib.eachDefaultSystem automatically handles macOS, Linux, etc:

outputs = { self, nixpkgs, flake-utils }:
  flake-utils.lib.eachDefaultSystem (system:
    # Your config here runs on all platforms
  );

A Complete Example: Team Ruby Project

{
  description = "Shared Ruby development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs { inherit system; };
      in
      {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            ruby_3_2
            bundler
            postgresql
            redis
          ];

          shellHook = ''
            echo "Ruby 3.2 dev environment loaded"
            echo "Available: ruby, bundler, postgres, redis"
          '';
        };
      }
    );
}
        

Version Control: What to Commit

Always commit:

flake.nix — your manifest
flake.lock — locked versions (critical for reproducibility)

Never commit:

.direnv/ — cache directory
result — symlink from builds

Updating Dependencies

When you want a newer version of nixpkgs:

nix flake update # Updates all inputs, regenerates flake.lock

Test it works, then commit both flake.nix and flake.lock together.

Handling Team Collaboration

Golden rule: Everyone commits and pushes flake.lock changes together. If person A updates dependencies, person B needs to pull and run nix flake update too.

Try It Yourself

Share Your Flake

Go to your my-nix-project directory:

cd my-nix-project
git init
git add flake.nix flake.lock
git commit -m "Add Nix development environment"

Test reproducibility (simulate a teammate):

cd /tmp
git clone /path/to/my-nix-project
cd my-nix-project
nix develop
node --version  # Should work!

Update dependencies:

cd my-nix-project
nix flake update
# Try nix develop again to verify it still works

Best Practices

Pin nixpkgs to a release: Use nixos-23.11, not unstable
Document your choices: Comments in flake.nix help teammates
Test locally first: Before pushing, run nix develop and verify tools work
Update together: Coordinate dependency updates with your team
Keep flake.lock clean: Don't manually edit it

Key Takeaways

flake.nix + flake.lock makes environments perfectly reproducible and shareable
Version control both files together
Use flake-utils to handle different platforms automatically
Teammates just need git + Nix to get your exact environment
Your setup is now resilient to system changes and time

← Lesson 5: Writing flake.nix Lesson 7: Advanced Patterns →