Skip to main content
Manage Android devices declaratively using Nix-on-Droid, bringing the power of NixOS-style configuration to mobile devices.

​
Overview

Nix-on-Droid configurations are stored in the droids/ directory. Each directory is automatically discovered and exposed as a nixOnDroidConfiguration.

​
Prerequisites

​
Android Device Requirements

  • Android device with ARM64 architecture (most modern devices)
  • Termux installed from F-Droid (NOT Google Play Store)
  • Storage permissions granted to Termux
  • Stable internet connection
  • At least 2GB free storage
Install Termux from F-Droid, not Google Play Store. The Play Store version is outdated and incompatible with Nix-on-Droid.

​
Initial Device Setup

Before deploying configurations, set up Nix-on-Droid on your device:
1

Install Termux

Download and install Termux from F-Droid.
2

Grant storage permissions

In Termux, run:
termux-setup-storage
Grant permission when prompted.
3

Install Nix-on-Droid

curl -fsSL https://raw.githubusercontent.com/nix-community/nix-on-droid/master/install.sh | bash
This installs Nix and sets up the Nix-on-Droid environment.
4

Restart Termux

Close and reopen Termux to load the new environment.

​
Flake Configuration

The flake uses automatic discovery for Nix-on-Droid configurations: 
nixOnDroidConfigurations = lib.mapAttrs mkDroid (lib.discover ./droids);
Each directory in droids/ is automatically available for deployment.

​
Architecture Settings

Nix-on-Droid configurations are built for aarch64-linux using the nixpkgs-droid input: 
mkDroid = name: path: let
  systemArch = "aarch64-linux";
  pkgs = import nixpkgs-droid {
    system = systemArch;
    config.allowUnfree = true;
  };
in
  nix-on-droid.lib.nixOnDroidConfiguration {
    inherit pkgs;
    modules = droidModules ++ [path];
  };

​
Deployment from Android Device

Deploy directly on the Android device itself.
1

Clone repository on device

In Termux:
cd ~
git clone <your-repo-url> homelab
cd homelab
2

Validate configuration

nix flake check
3

Deploy configuration

nix-on-droid switch --flake .#<device-name>
Replace <device-name> with your configuration name from droids/.

​
Deployment from Desktop

Build configurations on a desktop machine and deploy to the device.
1

Build on desktop

On your desktop/laptop:
cd /path/to/homelab
nix build .#nixOnDroidConfigurations.<device-name>.activationPackage
2

Copy to device

Transfer the built configuration:
# Find the result path
readlink -f result

# Copy via various methods:
# Method 1: Using adb
adb push result /data/data/com.termux/files/home/config

# Method 2: Using SSH (if configured)
scp -r result user@android-device:~/config

# Method 3: Via cloud storage or file sharing
# Upload result and download on device
3

Activate on device

In Termux on the Android device:
~/config/activate

​
Configuration Structure

Each Nix-on-Droid configuration should be structured as: 
droids/<device-name>/
├── default.nix      # Main configuration
├── home.nix         # Home Manager settings (optional)
└── packages.nix     # Device-specific packages (optional)

​
Home Manager Integration

Nix-on-Droid includes integrated Home Manager support: 
droidModules = [
  self.droidModules.default
  {
    home-manager = {
      useGlobalPkgs = true;
      extraSpecialArgs = { inherit inputs self lib; isDroid = true; };
      sharedModules = homeManagerModules;
      backupFileExtension = "bak";
    };
  }
];
Your device configuration can include Home Manager modules: 
# droids/phone/default.nix
{ pkgs, ... }:
{
  # Nix-on-Droid settings
  time.timeZone = "America/New_York";
  
  # Home Manager settings
  home-manager.config = { ... };
}

​
Common Configuration Examples

​
Basic Configuration

# droids/phone/default.nix
{ pkgs, ... }:
{
  # Set timezone
  time.timeZone = "America/New_York";
  
  # Install packages
  environment.packages = with pkgs; [
    vim
    git
    htop
    tmux
  ];
  
  # User configuration
  user.shell = "${pkgs.zsh}/bin/zsh";
}

​
With Home Manager

# droids/phone/default.nix
{ pkgs, ... }:
{
  time.timeZone = "America/New_York";
  
  environment.packages = with pkgs; [ vim git ];
  
  home-manager.config = {
    programs.zsh = {
      enable = true;
      enableCompletion = true;
      syntaxHighlighting.enable = true;
    };
    
    programs.git = {
      enable = true;
      userName = "Your Name";
      userEmail = "[email protected]";
    };
  };
}

​
Flake Reference Format

Nix-on-Droid uses this flake reference: 
.#<device-name>
Where:
  • . refers to the current directory (flake root)
  • # separates the flake reference from the output
  • <device-name> matches directory name in droids/

​
Rollback and Recovery

​
List Generations

nix-on-droid list-generations

​
Rollback to Previous Generation

nix-on-droid rollback

​
Switch to Specific Generation

nix-on-droid switch --rollback --generation <number>

​
Troubleshooting

​
Installation Issues

Problem: Nix installation fails on Android Solutions:
  1. Ensure Termux is from F-Droid
  2. Grant storage permissions
  3. Check internet connectivity
  4. Ensure sufficient storage space
  5. Try clearing Termux cache

​
Build Failures

Problem: Configuration fails to build Solutions:
  1. Run nix flake check first
  2. Verify architecture is aarch64-linux
  3. Check that all packages support ARM64
  4. Review error messages for unsupported packages
  5. Test build on desktop: nix build .#nixOnDroidConfigurations.<device-name>.activationPackage

​
Storage Issues

Problem: Running out of storage Solutions: 
# Clean old generations
nix-collect-garbage -d

# Check Nix store size
du -sh ~/.nix-profile

# Remove specific generations
nix-on-droid remove-generations 7d

​
Package Not Available

Problem: Package doesn’t work on Android Solutions:
  • Some packages don’t support ARM64 or Android
  • Check if package is in aarch64-linux cache
  • Consider alternatives or building from source
  • Review package meta.platforms

​
Performance Considerations

Initial builds on Android devices can be slow and battery-intensive. Consider building on a desktop and transferring the result.

​
Optimization Tips

  1. Use Binary Caches: Configure substituters to avoid building on device 
    nix.extraOptions = ''
  substituters = https://cache.nixos.org https://nix-community.cachix.org
'';
  2. Minimize Packages: Only install essential packages on device
  3. Build Remotely: Build on desktop when possible
  4. Cleanup Regularly: Remove old generations to save space

​
Remote Access

Configure SSH for remote access to your Android device: 
# droids/phone/default.nix
{ pkgs, ... }:
{
  environment.packages = [ pkgs.openssh ];
  
  # SSH daemon will be available in Termux
  # Start with: sshd
}

​
Best Practices

  • Test configurations on desktop first
  • Keep device configs minimal
  • Use binary caches to avoid local builds
  • Regularly clean old generations
  • Backup important data before major changes
  • Monitor storage usage
  • Keep Termux and Nix updated
Always run nix flake check before deploying to ensure configuration is valid. Failed deployments on Android can be harder to recover from.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us