Getting started

Welcome to Android Nix! We are happy that you are interested in giving it a try.

Note

Nix Android is an experimental project in active development. You may find bugs. We try our best to ship reliable APIs and to ensure any potential bugs are non-fatal (i.e., no security exposure, no data loss, etc).

If you find anything, please report it.

Install Android-Nix

Note

This step is highly recommended, but not required. The example Flake in the next step includes a suggested alternative.

Nixpkgs overlay

First, add android-nix to your Flake inputs:

 {
android-nix = {
  url = "git+https://codeberg.org/Android-Nix/android-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};
 }

Second, include the following overlay into your nixpkgs.overlays:

 {
nixpkgs.overlays = [
  (final: prev: {
    android-nix = inputs.android-nix.packages.${prev.stdenv.hostPlatform.system}.default;
  })
];
 }

An example flake.nix

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    android-nix = {
      url = "git+https://codeberg.org/Android-Nix/android-nix";
      inputs.nixpkgs.follows = "nixpkgs";
    };

    # ...
  };

  outputs =
    {
      self,
      nixpkgs,
      android-nix,
      ...
    }@inputs:
    let
      androidNixOverlay = final: prev: {
        android-nix = inputs.android-nix.packages.${prev.stdenv.hostPlatform.system}.default;
      };
    in
    {
      nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
        specialArgs = { inherit inputs; };
        modules = [
          ./configuration.nix
          {
            nixpkgs.overlays = [
              androidNixOverlay
            ];
          }
        ];
      };
    };
}

Then, you can include android-nix in your system’s packages:

 {
environment.systemPackages = with pkgs; [
  # This will be fetched from the `android-nix` flake rather than `nixpkgs`
  android-nix
]
 }

Nix Profile

Important

This method is imperative. The previous methods or the suggested alternative are recommended instead.

$ nix profile install git+https://codeberg.org/Android-Nix/android-nix

# If you want to remove the profile in the future:
$ nix profile remove android-nix

Set-up

To use Nix Android, you will first need to install Nix and enable Flake and the Nix command features.

Once you have installed and configured Nix, you will need to create an empty directory where your configuration will live. Inside this directory, create a flake.nix file with android-nix as your input. Then, you will be able to use android-nix.lib.mkConfiguration:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    # Include the Android Nix flake!
    android-nix = {
      url = "git+https://codeberg.org/Android-Nix/android-nix?ref=main";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, android-nix, ... }: {
    androidConfigurations.default = android-nix.lib.mkConfiguration {
      inherit nixpkgs;
      # The device's config is located in phone.nix
      modules = [ ./phone.nix ];
    };

    # Include this if you have not included `android-nix` in your system's packages.
    # This allows you to run `nix run . -- switch` instead of `android-nix switch`
    #packages.x86_64-linux.default = android-nix.packages.x86_64-linux.default;
  };
}

Your first `phone.nix`

Now that the initial set-up is done, you are ready to start using Android Nix!

If you have followed the instructions above, you will need to create a phone.nix file with content similar to the following:

# `android` provides you the Android Nix-specific APIs
{ android, ... }:

{
  # `android.apps` contains the low-level APIs and abstractions
  # to install any app you would like.
  #
  # F-Droid and IzzyOnDroid are natively supported in `fdroid`
  # and `izzyondroid` respectively. Low-level APIs are available
  # inside `lib`.
  #
  # More info in the `Applications` section.
  apps = with android.apps; [
    fdroid.org_videolan_vlc
  ];

  # No need to declare these inside `apps`, Nix Android will
  # identify them and include them in the installation bundle.
  defaultApps = with android.apps; {
    "android.app.role.BROWSER" = fdroid.org_mozilla_fennec_fdroid;
  };

  disabledApps = [
    "com.android.egg"
  ];
}

Once you are happy with your config, you can run:

nix flake update to retrieve the latest Android Nix version (incl. the latest app versions),
android-nix switch to apply the config to your device.

Make sure that your device is connected to your computer with ADB enabled. If a pop-up appears on your phone with “Allow USB debugging”, you need to accept it.

Warning

ADB is a powerful tool that can be used by bad actors to infiltrate your device. Nix Android does not audit, host, or build the APKs you can retrieve through it. Think of Nix Android as a slightly more advanced ADB+F-Droid client.

Follow security best practices, disable ADB when not in use, and monitor the software you install and run on your devices.

Nix Android is fully Free Software, you can freely study its code. If you find any vulnerabilities or have concrete security concerns, please report them.

Keyboard shortcuts