Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/soriphoono/homelab/llms.txt

Use this file to discover all available pages before exploring further.

Home Manager allows you to manage user-level configurations independently of system configuration. This is useful for standalone installations on non-NixOS systems or for user-specific settings.

​
Overview

Home Manager configurations are stored in the homes/ directory with support for three naming patterns:
  • <user> - Base configuration used everywhere
  • <user>@global - Supplementary config for standalone installs
  • <user>@<hostname> - Machine-specific overrides (integrated with NixOS, not standalone)

​
Understanding Home Configurations

The flake automatically combines configurations: 
homeConfigurations = let
  # Scans for <user> and <user>@global, combines them if both exist
  usernames = lib.unique (map (name: lib.removeSuffix "@global" name) validUsers);
in
  lib.genAttrs usernames mkHome;

​
Standalone Deployment

Deploy Home Manager independently of NixOS systems.
1

Navigate to repository

cd /path/to/homelab
2

Validate configuration

nix flake check
3

Deploy Home Manager

home-manager switch --flake .#<username>
Replace <username> with your username (the directory name in homes/).

​
Flake Reference Format

Home Manager uses this flake reference format: 
.#<username>
Where:
  • . refers to the current directory (flake root)
  • # separates the flake reference from the output
  • <username> matches homes/<username> or homes/<username>@global
Do NOT use <username>@<hostname> for standalone deployments. These machine-specific configs are automatically integrated by NixOS systems and are not exposed as standalone configurations.

​
Configuration Patterns

​
Base Configuration Only

For users who only need basic settings: 
homes/
└── alice/
    └── default.nix
Deploy with: 
home-manager switch --flake .#alice

​
Base + Global Configuration

For users who want different settings on NixOS vs. standalone: 
homes/
├── alice/
│   └── default.nix      # Used on all systems
└── alice@global/
    └── default.nix      # Additional config for standalone
Deploy with: 
home-manager switch --flake .#alice
Both alice and alice@global are automatically combined.

​
Base + Machine-Specific

For users on NixOS systems with per-machine customization: 
homes/
├── alice/
│   └── default.nix      # Base configuration
└── alice@workstation/
    └── default.nix      # Overrides for specific host
Machine-specific configs (alice@workstation) are integrated by NixOS automatically. Deploy the system instead:
sudo nixos-rebuild switch --flake .#workstation

​
Deployment Commands

# Build and activate new configuration
home-manager switch --flake .#<username>

​
NixOS Integration

On NixOS systems, Home Manager is integrated automatically through the system configuration.

​
How It Works

The flake includes Home Manager as a NixOS module: 
nixosModules = [
  home-manager.nixosModules.home-manager
  {
    home-manager = {
      useGlobalPkgs = true;
      useUserPackages = true;
      extraSpecialArgs = { inherit inputs self lib; isDroid = false; };
      sharedModules = homeManagerModules;
      backupFileExtension = "bak";
    };
  }
];

​
System-Integrated Deployment

When deploying a NixOS system, Home Manager configs are applied automatically: 
sudo nixos-rebuild switch --flake .#<hostname>
This deploys:
  1. The system configuration from systems/<hostname>/
  2. Base home config from homes/<user>/
  3. Machine-specific home config from homes/<user>@<hostname>/ (if exists)

​
First-Time Installation

If Home Manager is not yet installed on your system:
1

Install Home Manager

nix run home-manager/master -- init --switch
2

Or use from flake directly

nix run .#homeConfigurations.<username>.activationPackage

​
Rollback and Recovery

​
Rollback to Previous Generation

home-manager generations
# Note the generation number
/nix/store/<hash>-home-manager-generation/activate

​
List Generations with Details

home-manager generations | head -10

​
Remove Old Generations

home-manager expire-generations "-7 days"

​
Cross-Platform Support

Home Manager works on:
  • NixOS (integrated or standalone)
  • Other Linux distributions
  • macOS (Darwin)
  • WSL (Windows Subsystem for Linux)

​
Non-NixOS Linux Example

On Ubuntu, Fedora, Arch, etc.: 
# Install Nix first
curl -L https://nixos.org/nix/install | sh

# Clone your homelab repo
git clone <your-repo-url>
cd homelab

# Deploy your home configuration
home-manager switch --flake .#<username>

​
Configuration Management

​
System Architecture Detection

The configuration automatically detects system architecture from meta.nix: 
meta = {
  system = "x86_64-linux";  # or "aarch64-linux", "x86_64-darwin", etc.
};

​
Default Settings

The builder sets sensible defaults: 
home = {
  inherit username;
  homeDirectory = lib.mkDefault "/home/${username}";
  stateVersion = lib.mkDefault "24.11";
};

​
Troubleshooting

​
File Conflicts

If Home Manager encounters existing files: 
error: Existing file '/home/user/.bashrc' would be overwritten
Solutions:
  1. Backup and remove the file: mv ~/.bashrc ~/.bashrc.bak
  2. Home Manager will create .bak backups automatically (configured in flake)
  3. Or use home-manager switch -b backup for custom backup extension

​
Permission Issues

# Home Manager should run as your user, not root
home-manager switch --flake .#<username>

# NOT: sudo home-manager switch

​
Build Failures

  1. Validate first: nix flake check
  2. Check for syntax errors in homes/<username>/default.nix
  3. Verify all referenced modules exist
  4. Review error messages for missing options

​
Module Not Found

If custom modules aren’t found: 
# In homes/<username>/default.nix
imports = [
  ../../modules/home/custom-module  # Ensure path is correct
];

​
Best Practices

  • Keep base configuration minimal and shared
  • Use @global for standalone-specific packages
  • Test on non-critical machines first
  • Version control all changes
  • Run nix flake check before deploying
  • Document complex configurations
Always validate with nix flake check before deploying. The flake check is mandatory before any deployment.

​
Advanced Usage

​
Update Home Manager

nix flake lock --update-input home-manager
home-manager switch --flake .#<username>

​
Show Configuration Diff

# Build new config
home-manager build --flake .#<username>

# Compare with current
nvd diff ~/.nix-profile ./result

​
Manual Activation

nix build .#homeConfigurations.<username>.activationPackage
./result/activate

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us