dot/MIGRATION.md

Migration Guide: Channels → Flakes

Why Migrate to Flakes?

✅ Reproducibility: Lock files pin exact package versions ✅ Latest unstable packages: Easy access to nixos-unstable ✅ Better for dotfiles: Version control with exact dependencies ✅ Modern approach: Future of Nix configuration ✅ You're ready: You already have flakes enabled!

Current State (Channels)

Your current setup:

/etc/nixos/configuration.nix  # Channel-based, imports from <nixos-wsl/modules>

Commands:

sudo nix-channel --update
sudo nixos-rebuild switch

Target State (Flakes)

New setup:

/home/pan/dev/config/dot/nix/nixos/
├── flake.nix           # Declares inputs (nixpkgs, nixos-wsl, home-manager)
├── configuration.nix   # System config (no imports needed)
├── home.nix           # Your user config
└── modules/           # User modules

Commands:

nix flake update  # Update dependencies
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix

Migration Steps

Step 1: Test the Flake Configuration

First, let's make sure it builds without applying:

cd /home/pan/dev/config/dot/nix/nixos
nix flake check --impure  # Validate syntax
sudo nixos-rebuild build --flake .#nix --impure  # Test build

If successful, you'll see a result symlink. The --impure flag is needed for NIX_LD settings.

Step 2: Review What Will Change

Compare your current and new configs:

diff /etc/nixos/configuration.nix /home/pan/dev/config/dot/nix/nixos/configuration.nix

Key differences:

• ❌ Removed: imports = [ <nixos-wsl/modules> <home-manager/nixos> ]
• ✅ Added: Flake manages these as inputs
• ✅ Uses: nixos-unstable (latest packages)
• ✅ Locks: Exact versions in flake.lock

Step 3: Apply the Flake Configuration

Option A: Direct (Recommended)

sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure

Option B: Symlink to /etc/nixos (Optional)

sudo mv /etc/nixos/configuration.nix /etc/nixos/configuration.nix.backup
sudo ln -s /home/pan/dev/config/dot/nix/nixos/flake.nix /etc/nixos/flake.nix
sudo ln -s /home/pan/dev/config/dot/nix/nixos/configuration.nix /etc/nixos/configuration.nix
sudo nixos-rebuild switch --flake /etc/nixos#nix --impure

Step 4: Verify Everything Works

After switching:

# Check system info
nixos-version

# Check flake info
nix flake metadata /home/pan/dev/config/dot/nix/nixos

# Test your tools
zsh --version
tmux -V
nvim --version
git --version
task --version

Step 5: Set Up Convenient Alias (Optional)

Add to your shell config:

alias nixos-update='cd /home/pan/dev/config/dot/nix/nixos && nix flake update && sudo nixos-rebuild switch --flake .#nix --impure'
alias nixos-rebuild-switch='sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure'

Rollback Plan

If anything goes wrong, you can always rollback:

# List generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to previous generation
sudo nixos-rebuild switch --rollback

# Or select from boot menu
# Reboot and choose previous generation

Your old channel-based config is still at /etc/nixos/configuration.nix.backup.

Common Commands

With Flakes

# Update all inputs (nixpkgs, home-manager, nixos-wsl)
nix flake update

# Update just one input
nix flake lock --update-input nixpkgs

# Apply configuration
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure

# Test without applying
sudo nixos-rebuild build --flake /home/pan/dev/config/dot/nix/nixos#nix --impure

# Check what changed
nix flake metadata /home/pan/dev/config/dot/nix/nixos
git diff flake.lock  # See version changes

Garbage Collection

# Delete old generations (save disk space)
sudo nix-collect-garbage --delete-older-than 30d

# Full cleanup
sudo nix-collect-garbage -d
sudo nix-store --optimise

FAQ

Do I need to remove channels?

No, but you can clean them up:

sudo nix-channel --list  # See current channels
sudo nix-channel --remove nixos  # Remove if desired

Will my existing packages break?

No! The flake uses the same package set (nixos-unstable). Your home-manager config stays the same.

What about --impure flag?

You need it because home.nix uses NIX_LD which reads from the store at evaluation time. This is fine and expected for this use case.

Can I still use nixos-rebuild switch without flags?

Not directly with flakes. But you can:

1. Create an alias (see Step 5)
2. Symlink to /etc/nixos/flake.nix and use --flake /etc/nixos#nix

How do I update packages now?

# Update flake.lock to latest versions
nix flake update

# Then rebuild
sudo nixos-rebuild switch --flake /home/pan/dev/config/dot/nix/nixos#nix --impure

Benefits You'll Get

1. Exact versions: flake.lock pins everything
2. Faster updates: Only download what changed
3. Better caching: Flakes have better binary cache hits
4. Git-friendly: Your whole system in version control
5. Easy sharing: Others can reproduce your exact system

Next Steps After Migration

1. ✅ Commit your configuration to git
2. ✅ Remove old channels (optional)
3. ✅ Set up shell aliases
4. ✅ Enjoy reproducible configs! 🎉