> ## 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.

# Deploying Home Manager

> Deploy and manage user-level configurations with Home Manager

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:

```nix theme={null}
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.

<Steps>
  <Step title="Navigate to repository">
    ```bash theme={null}
    cd /path/to/homelab
    ```
  </Step>

  <Step title="Validate configuration">
    ```bash theme={null}
    nix flake check
    ```
  </Step>

  <Step title="Deploy Home Manager">
    ```bash theme={null}
    home-manager switch --flake .#<username>
    ```

    Replace `<username>` with your username (the directory name in `homes/`).
  </Step>
</Steps>

## 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`

<Warning>
  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.
</Warning>

## Configuration Patterns

### Base Configuration Only

For users who only need basic settings:

```
homes/
└── alice/
    └── default.nix
```

Deploy with:

```bash theme={null}
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:

```bash theme={null}
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
```

<Warning>
  Machine-specific configs (`alice@workstation`) are integrated by NixOS automatically. Deploy the system instead:

  ```bash theme={null}
  sudo nixos-rebuild switch --flake .#workstation
  ```
</Warning>

## Deployment Commands

<CodeGroup>
  ```bash switch theme={null}
  # Build and activate new configuration
  home-manager switch --flake .#<username>
  ```

  ```bash build theme={null}
  # Build without activating
  home-manager build --flake .#<username>
  ```

  ```bash generations theme={null}
  # List previous generations
  home-manager generations
  ```
</CodeGroup>

## 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:

```nix theme={null}
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:

```bash theme={null}
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:

<Steps>
  <Step title="Install Home Manager">
    ```bash theme={null}
    nix run home-manager/master -- init --switch
    ```
  </Step>

  <Step title="Or use from flake directly">
    ```bash theme={null}
    nix run .#homeConfigurations.<username>.activationPackage
    ```
  </Step>
</Steps>

## Rollback and Recovery

### Rollback to Previous Generation

```bash theme={null}
home-manager generations
# Note the generation number
/nix/store/<hash>-home-manager-generation/activate
```

### List Generations with Details

```bash theme={null}
home-manager generations | head -10
```

### Remove Old Generations

```bash theme={null}
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.:

```bash theme={null}
# 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`:

```nix theme={null}
meta = {
  system = "x86_64-linux";  # or "aarch64-linux", "x86_64-darwin", etc.
};
```

### Default Settings

The builder sets sensible defaults:

```nix theme={null}
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

```bash theme={null}
# 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:

```nix theme={null}
# 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

<Warning>
  Always validate with `nix flake check` before deploying. The flake check is mandatory before any deployment.
</Warning>

## Advanced Usage

### Update Home Manager

```bash theme={null}
nix flake lock --update-input home-manager
home-manager switch --flake .#<username>
```

### Show Configuration Diff

```bash theme={null}
# Build new config
home-manager build --flake .#<username>

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

### Manual Activation

```bash theme={null}
nix build .#homeConfigurations.<username>.activationPackage
./result/activate
```

## Next Steps

* [NixOS Systems](/deployment/nixos-systems) - Full system deployment
* [Nix-on-Droid](/deployment/nix-on-droid) - Android configurations
* [Validation](/deployment/validation) - Pre-deployment checks