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.
Deploy Home Manager
home-manager switch --flake .#<username>
<username> with your username (the directory name in homes/).
. 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
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
home-manager switch --flake .#alice
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>
- The system configuration from
systems/<hostname>/
- Base home config from
homes/<user>/
- Machine-specific home config from
homes/<user>@<hostname>/ (if exists)
First-Time Installation
If Home Manager is not yet installed on your system:
Install Home Manager
nix run home-manager/master -- init --switch
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"
- 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
- Backup and remove the file:
mv ~/.bashrc ~/.bashrc.bak
- Home Manager will create
.bak backups automatically (configured in flake)
- 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
- Validate first:
nix flake check
- Check for syntax errors in
homes/<username>/default.nix
- Verify all referenced modules exist
- 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