2023-06-25 05:41:51 +00:00
[<img src="https://daiderd.com/nix-darwin/images/nix-darwin.png" width="200px" alt="logo" /> ](https://github.com/LnL7/nix-darwin )
2017-02-19 16:49:00 +00:00
2016-12-12 16:37:50 +00:00
# nix-darwin
2016-11-01 20:25:22 +00:00
2020-03-28 18:24:59 +00:00
2017-02-19 14:00:27 +00:00
2016-12-15 11:39:56 +00:00
Nix modules for darwin, `/etc/nixos/configuration.nix` for macOS.
2016-12-15 21:03:06 +00:00
2022-09-02 12:34:18 +00:00
This project aims to bring the convenience of a declarative system approach to macOS.
2023-06-20 14:00:28 +00:00
nix-darwin is built up around [Nixpkgs ](https://github.com/NixOS/nixpkgs ), quite similar to [NixOS ](https://nixos.org/ ).
2022-09-02 12:34:18 +00:00
2023-06-20 14:00:28 +00:00
## Installing
2016-12-11 12:33:01 +00:00
2022-09-02 12:34:18 +00:00
To install nix-darwin, a working installation of [Nix ](https://github.com/NixOS/nix#installation ) is required.
2022-09-02 11:48:07 +00:00
2023-06-20 14:00:28 +00:00
> NOTE: Using `darwin-installer` is no longer necessary on flake based systems.
2017-06-03 09:27:22 +00:00
```bash
2018-01-14 18:29:30 +00:00
nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A installer
./result/bin/darwin-installer
2017-06-03 09:27:22 +00:00
```
2018-01-14 18:29:30 +00:00
> NOTE: the system activation scripts don't overwrite existing etc files, so files like `/etc/bashrc` and `/etc/zshrc` won't be
> updated by default. If you didn't use the installer or skipped some of the options you'll have to take care of this yourself.
> Either modify the existing file to source/import the one from `/etc/static` or remove it. Some examples:
2017-06-03 09:24:48 +00:00
2023-07-11 08:58:29 +00:00
- `mv /etc/bashrc /etc/bashrc.before-nix-darwin`
2017-06-03 09:24:48 +00:00
- `echo 'if test -e /etc/static/bashrc; then . /etc/static/bashrc; fi' | sudo tee -a /etc/bashrc`
2017-06-03 10:00:13 +00:00
## Updating
2018-01-14 18:29:30 +00:00
The installer will configure a channel for this repository.
2017-06-03 10:00:13 +00:00
```bash
2017-09-06 21:37:34 +00:00
nix-channel --update darwin
2017-07-24 21:27:41 +00:00
darwin-rebuild changelog
2017-06-03 10:00:13 +00:00
```
2022-09-02 12:34:18 +00:00
> NOTE: If you are using Nix as a daemon service the channel for that will be owned by root.
2022-09-02 11:48:07 +00:00
> Use `sudo -i nix-channel --update darwin` instead.
2018-01-15 23:54:35 +00:00
## Uninstalling
There's also an uninstaller if you don't like the project and want to
remove the configured files and services.
```bash
nix-build https://github.com/LnL7/nix-darwin/archive/master.tar.gz -A uninstaller
./result/bin/darwin-uninstaller
```
2017-06-03 09:24:48 +00:00
## Example configuration
2021-05-04 04:26:54 +00:00
Configuration lives in `~/.nixpkgs/darwin-configuration.nix` . Check out
[modules/examples ](https://github.com/LnL7/nix-darwin/tree/master/modules/examples ) for some example configurations.
2017-06-03 09:24:48 +00:00
```nix
{ pkgs, ... }:
{
# List packages installed in system profile. To search by name, run:
# $ nix-env -qaP | grep wget
environment.systemPackages =
2018-08-21 20:42:33 +00:00
[ pkgs.vim
2017-06-03 09:24:48 +00:00
];
2018-03-26 20:47:40 +00:00
# Auto upgrade nix package and the daemon service.
services.nix-daemon.enable = true;
nix.package = pkgs.nix;
2017-06-03 09:24:48 +00:00
}
```
2020-10-18 15:02:45 +00:00
## Flakes (experimental)
2020-10-25 10:49:59 +00:00
There is also preliminary support for building your configuration using a [flake ](https://nixos.wiki/wiki/Flakes ). This
2020-10-18 15:02:45 +00:00
is mostly based on the flake support that was added to NixOS.
2023-06-20 14:00:28 +00:00
### Step 1. Creating `flake.nix`
< details >
< summary > Getting started from scratch< / summary >
< p > < / p >
If you don't have an existing `configuration.nix` , you can run the following commands to generate a basic `flake.nix` inside `~/.config/nix-darwin` :
```bash
mkdir -p ~/.config/nix-darwin
cd ~/.config/nix-darwin
nix flake init -t nix-darwin
```
Make sure to replace all occurrences of `simple` with your short hostname which you can find by running `hostname -s` .
> NOTE: Make sure to change `nixpkgs.hostPlatform` to `aarch64-darwin` if you are using Apple Silicon.
< / details >
< details >
< summary > Migrating from an existing configuration.nix< / summary >
< p > < / p >
Add the following to `flake.nix` in the same folder as `configuration.nix` :
2020-10-18 15:02:45 +00:00
```nix
{
description = "John's darwin system";
inputs = {
2023-06-20 14:00:28 +00:00
nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-23.05-darwin";
2023-07-12 00:36:14 +00:00
nix-darwin.url = "github:LnL7/nix-darwin/master";
nix-darwin.inputs.nixpkgs.follows = "nixpkgs";
2020-10-18 15:02:45 +00:00
};
2023-08-04 20:18:10 +00:00
outputs = inputs@{ self, nix-darwin, nixpkgs }: {
darwinConfigurations."Johns-MacBook" = nix-darwin.lib.darwinSystem {
2020-10-18 15:02:45 +00:00
modules = [ ./configuration.nix ];
};
};
}
```
2023-06-20 14:00:28 +00:00
Make sure to replace `Johns-MacBook` with your short hostname which you can find by running `hostname -s` .
> NOTE: Make sure to set `nixpkgs.hostPlatform` in your `configuration.nix` to either `x86_64-darwin` (Intel) or `aarch64-darwin` (Apple Silicon).
< / details >
### Step 2. Installing `nix-darwin`
Instead of using `darwin-installer` , you can just run `darwin-rebuild switch` to install nix-darwin. As `darwin-rebuild` won't be installed in your `PATH` yet, you can use the following command:
```bash
nix run nix-darwin -- switch --flake ~/.config/nix-darwin
```
### Step 3. Using `nix-darwin`
After installing, you can run `darwin-rebuild` to apply changes to your system:
```bash
darwin-rebuild switch --flake ~/.config/nix-darwin
```
#### Using flake inputs
eval-config: rationalize handling of Nixpkgs
This is a big change that disentangles a lot of mistaken assumptions
about mixing multiple versions of Nixpkgs, treating external flake
inputs as gospel for the source of Nixpkgs and nix-darwin, etc.;
the end result should be much simpler conceptually, but it will be a
breaking change for anyone using `eval-config.nix` directly. Hopefully
that shouldn't be a big issue, as it is more of an internal API and
it's quite likely that existing uses may have been broken in the same
way the internal ones were.
It was previously easy to get into a state where your `lib` comes
from nix-darwin's `nixpkgs` input or a global channel and your
`pkgs` comes from another major version of Nixpkgs. This is pretty
fundamentally broken due to the coupling of `pkgs` to its corresponding
`lib`, but the brokenness was hidden much of the time until something
surfaced it. Now there is exactly one mandatory `lib` input to system
evaluation, and the handling of various additional options like `pkgs`
and `system` can be done modularly; maintaining backwards compatibility
with the previous calling convention is punted to the `default.nix`
and `lib.darwinSystem` entry points. `inputs` is no longer read by
nix-darwin or special in any way, merely a convention for user code,
and the argument is retained in the entry points only for backwards
compatibility.
All correct invocations of the entry points should keep working
after this change, and some previously-broken ones should be fixed
too. The documentation and template have been adjusted to show the
newly-recommended modular way of specifying various things, but no
deprecation warnings have been introduced yet by this change.
There is one potential, mostly cosmetic regression:
`system.nixpkgsRevision` and related options are less likely to be
set than before, in cases where it is not possible to determine the
origin of the package set. Setting `nixpkgs.source` explicitly will
make this work again, and I hope to look into sending changes upstream
to Nixpkgs to make `lib.trivial.revisionWithDefault` behave properly
under flakes, which would fix this regression and potentially allow
reducing some of the complexity.
Fixes: #669
2023-07-07 08:02:38 +00:00
Inputs from the flake can also be passed into `darwinSystem` . These inputs are then
2023-06-12 06:08:03 +00:00
accessible as an argument `inputs` , similar to `pkgs` and `lib` , inside the configuration.
2020-10-18 15:02:45 +00:00
```nix
eval-config: rationalize handling of Nixpkgs
This is a big change that disentangles a lot of mistaken assumptions
about mixing multiple versions of Nixpkgs, treating external flake
inputs as gospel for the source of Nixpkgs and nix-darwin, etc.;
the end result should be much simpler conceptually, but it will be a
breaking change for anyone using `eval-config.nix` directly. Hopefully
that shouldn't be a big issue, as it is more of an internal API and
it's quite likely that existing uses may have been broken in the same
way the internal ones were.
It was previously easy to get into a state where your `lib` comes
from nix-darwin's `nixpkgs` input or a global channel and your
`pkgs` comes from another major version of Nixpkgs. This is pretty
fundamentally broken due to the coupling of `pkgs` to its corresponding
`lib`, but the brokenness was hidden much of the time until something
surfaced it. Now there is exactly one mandatory `lib` input to system
evaluation, and the handling of various additional options like `pkgs`
and `system` can be done modularly; maintaining backwards compatibility
with the previous calling convention is punted to the `default.nix`
and `lib.darwinSystem` entry points. `inputs` is no longer read by
nix-darwin or special in any way, merely a convention for user code,
and the argument is retained in the entry points only for backwards
compatibility.
All correct invocations of the entry points should keep working
after this change, and some previously-broken ones should be fixed
too. The documentation and template have been adjusted to show the
newly-recommended modular way of specifying various things, but no
deprecation warnings have been introduced yet by this change.
There is one potential, mostly cosmetic regression:
`system.nixpkgsRevision` and related options are less likely to be
set than before, in cases where it is not possible to determine the
origin of the package set. Setting `nixpkgs.source` explicitly will
make this work again, and I hope to look into sending changes upstream
to Nixpkgs to make `lib.trivial.revisionWithDefault` behave properly
under flakes, which would fix this regression and potentially allow
reducing some of the complexity.
Fixes: #669
2023-07-07 08:02:38 +00:00
# in flake.nix
2023-07-12 00:36:14 +00:00
nix-darwin.lib.darwinSystem {
2023-06-12 06:08:03 +00:00
modules = [ ./configuration.nix ];
eval-config: rationalize handling of Nixpkgs
This is a big change that disentangles a lot of mistaken assumptions
about mixing multiple versions of Nixpkgs, treating external flake
inputs as gospel for the source of Nixpkgs and nix-darwin, etc.;
the end result should be much simpler conceptually, but it will be a
breaking change for anyone using `eval-config.nix` directly. Hopefully
that shouldn't be a big issue, as it is more of an internal API and
it's quite likely that existing uses may have been broken in the same
way the internal ones were.
It was previously easy to get into a state where your `lib` comes
from nix-darwin's `nixpkgs` input or a global channel and your
`pkgs` comes from another major version of Nixpkgs. This is pretty
fundamentally broken due to the coupling of `pkgs` to its corresponding
`lib`, but the brokenness was hidden much of the time until something
surfaced it. Now there is exactly one mandatory `lib` input to system
evaluation, and the handling of various additional options like `pkgs`
and `system` can be done modularly; maintaining backwards compatibility
with the previous calling convention is punted to the `default.nix`
and `lib.darwinSystem` entry points. `inputs` is no longer read by
nix-darwin or special in any way, merely a convention for user code,
and the argument is retained in the entry points only for backwards
compatibility.
All correct invocations of the entry points should keep working
after this change, and some previously-broken ones should be fixed
too. The documentation and template have been adjusted to show the
newly-recommended modular way of specifying various things, but no
deprecation warnings have been introduced yet by this change.
There is one potential, mostly cosmetic regression:
`system.nixpkgsRevision` and related options are less likely to be
set than before, in cases where it is not possible to determine the
origin of the package set. Setting `nixpkgs.source` explicitly will
make this work again, and I hope to look into sending changes upstream
to Nixpkgs to make `lib.trivial.revisionWithDefault` behave properly
under flakes, which would fix this regression and potentially allow
reducing some of the complexity.
Fixes: #669
2023-07-07 08:02:38 +00:00
specialArgs = { inherit inputs; };
2020-10-18 15:02:45 +00:00
}
2023-06-12 06:08:03 +00:00
```
```nix
eval-config: rationalize handling of Nixpkgs
This is a big change that disentangles a lot of mistaken assumptions
about mixing multiple versions of Nixpkgs, treating external flake
inputs as gospel for the source of Nixpkgs and nix-darwin, etc.;
the end result should be much simpler conceptually, but it will be a
breaking change for anyone using `eval-config.nix` directly. Hopefully
that shouldn't be a big issue, as it is more of an internal API and
it's quite likely that existing uses may have been broken in the same
way the internal ones were.
It was previously easy to get into a state where your `lib` comes
from nix-darwin's `nixpkgs` input or a global channel and your
`pkgs` comes from another major version of Nixpkgs. This is pretty
fundamentally broken due to the coupling of `pkgs` to its corresponding
`lib`, but the brokenness was hidden much of the time until something
surfaced it. Now there is exactly one mandatory `lib` input to system
evaluation, and the handling of various additional options like `pkgs`
and `system` can be done modularly; maintaining backwards compatibility
with the previous calling convention is punted to the `default.nix`
and `lib.darwinSystem` entry points. `inputs` is no longer read by
nix-darwin or special in any way, merely a convention for user code,
and the argument is retained in the entry points only for backwards
compatibility.
All correct invocations of the entry points should keep working
after this change, and some previously-broken ones should be fixed
too. The documentation and template have been adjusted to show the
newly-recommended modular way of specifying various things, but no
deprecation warnings have been introduced yet by this change.
There is one potential, mostly cosmetic regression:
`system.nixpkgsRevision` and related options are less likely to be
set than before, in cases where it is not possible to determine the
origin of the package set. Setting `nixpkgs.source` explicitly will
make this work again, and I hope to look into sending changes upstream
to Nixpkgs to make `lib.trivial.revisionWithDefault` behave properly
under flakes, which would fix this regression and potentially allow
reducing some of the complexity.
Fixes: #669
2023-07-07 08:02:38 +00:00
# in configuration.nix
{ pkgs, lib, inputs }:
2023-07-12 00:36:14 +00:00
# inputs.self, inputs.nix-darwin, and inputs.nixpkgs can be accessed here
2020-10-18 15:02:45 +00:00
```
2017-06-03 09:24:48 +00:00
## Manual Install
2016-12-11 12:49:00 +00:00
2016-12-11 12:33:01 +00:00
```bash
2017-10-10 20:21:30 +00:00
# Configure the channel
nix-channel --add https://github.com/LnL7/nix-darwin/archive/master.tar.gz darwin
nix-channel --update
2019-10-17 12:59:00 +00:00
export NIX_PATH=darwin-config=$HOME/.nixpkgs/darwin-configuration.nix:$HOME/.nix-defexpr/channels:$NIX_PATH
2016-12-11 14:17:04 +00:00
2017-10-10 20:21:30 +00:00
# Or use a local git repository
git clone git@github.com:LnL7/nix-darwin.git ~/.nix-defexpr/darwin
2016-12-15 14:03:57 +00:00
export NIX_PATH=darwin=$HOME/.nix-defexpr/darwin:darwin-config=$HOME/.nixpkgs/darwin-configuration.nix:$NIX_PATH
2016-12-11 12:33:01 +00:00
2017-10-10 20:21:30 +00:00
cp ~/.nix-defexpr/darwin/modules/examples/simple.nix ~/.nixpkgs/darwin-configuration.nix
2016-12-15 14:03:57 +00:00
# you can also use this to rebootstrap nix-darwin in case
# darwin-rebuild is to old to activate the system.
$(nix-build '< darwin > ' -A system --no-out-link)/sw/bin/darwin-rebuild build
2016-12-15 11:39:56 +00:00
$(nix-build '< darwin > ' -A system --no-out-link)/sw/bin/darwin-rebuild switch
2017-01-05 22:57:09 +00:00
. /etc/static/bashrc
2016-12-15 11:39:56 +00:00
```
2017-03-12 00:00:10 +00:00
... or for `fish` :
```fish
(nix-build '< darwin > ' -A system --no-out-link)/sw/bin/darwin-rebuild build
(nix-build '< darwin > ' -A system --no-out-link)/sw/bin/darwin-rebuild switch
```
2023-06-20 14:00:28 +00:00
This will create and manage a system profile in `/run/current-system` , just like NixOS.
2017-03-12 15:35:56 +00:00
2023-06-20 14:00:28 +00:00
By default, nix-darwin will look in your `NIX_PATH` for this repository at `~/.nix-defexpr/darwin` and your configuration at `~/.nixpkgs/darwin-configuration.nix` .
2017-03-12 15:35:56 +00:00
If you want to change these you can set your own with `nix.nixPath = [ ];` .
```
$ darwin-rebuild switch
building the system configuration...
these derivations will be built:
/nix/store/vfad6xgjzr56jcs051cg6vzch4dby92y-etc-zprofile.drv
/nix/store/cbmkscxsz0k02ynaph5xaxm1aql0p3vq-etc.drv
/nix/store/r5fpn177jhc16f8iyzk12gcw4pivzpbw-nixdarwin-system-16.09.drv
building path(s) ‘ ’
building path(s) ‘ ’
building path(s) ‘ ’
setting up /etc...
setting up launchd services...
writing defaults...
$
```
2022-09-02 11:48:07 +00:00
## Documentation
2023-06-25 05:41:51 +00:00
Reference documentation of all the options is available [here ](https://daiderd.com/nix-darwin/manual/index.html ).
2022-09-02 11:48:07 +00:00
This can also be accessed locally using `man 5 configuration.nix` .
2022-09-02 12:34:18 +00:00
`darwin-help` will open a HTML version of the manpage in the default browser.
2022-09-02 11:48:07 +00:00
2022-09-02 12:34:18 +00:00
Furthermore there's `darwin-option` to introspect the settings of a system and its available options.
> NOTE: `darwin-option` is only available to non-flake installations.
2022-09-02 11:48:07 +00:00
2017-03-12 15:35:56 +00:00
```
2020-10-18 15:02:45 +00:00
$ darwin-option services.activate-system.enable
2017-03-12 15:35:56 +00:00
Value:
true
Default:
false
Example:
no example
Description:
Whether to activate system at boot time.
```
2019-05-04 14:10:00 +00:00
There's also a small wiki https://github.com/LnL7/nix-darwin/wiki about
specific topics, like macOS upgrades.
2017-07-19 19:30:28 +00:00
2017-11-05 21:16:51 +00:00
## Tests
There are basic tests that run sanity checks for some of the modules,
you can run them like this:
```bash
2022-09-02 12:34:18 +00:00
# run all tests
2022-09-02 11:48:07 +00:00
nix-build release.nix -A tests
2022-09-02 12:34:18 +00:00
# or just a subset
2017-11-05 21:16:51 +00:00
nix-build release.nix -A tests.environment-path
```
2017-07-19 19:30:28 +00:00
## Contributing
2023-06-20 14:00:28 +00:00
Let's make Nix on macOS awesome!
2017-07-19 19:30:28 +00:00
Don't hesitate to contribute modules or open an issue.
2017-10-06 17:42:43 +00:00
To build your configuration with local changes you can run this. This
flag can also be used to override darwin-config or nixpkgs, for more
2022-09-02 11:48:07 +00:00
information on the `-I` flag look at the nix-build [manpage ](https://nixos.org/manual/nix/stable/command-ref/nix-build.html ).
2017-10-06 17:42:43 +00:00
2017-11-05 21:16:51 +00:00
```bash
2017-10-06 17:42:43 +00:00
darwin-rebuild switch -I darwin=.
```
2021-03-07 14:46:08 +00:00
If you're adding a module, please add yourself to `meta.maintainers` , for example
```nix
meta.maintainers = [
lib.maintainers.alice or "alice"
];
options.services.alicebot = # ...
```
The `or` operator takes care of graceful degradation when `lib` from Nixpkgs
goes out of sync.
2017-07-19 19:30:28 +00:00
Also feel free to contact me if you have questions,
2022-08-29 23:33:56 +00:00
- Matrix - @daiderd:matrix .org, you can find me in [#macos:nixos.org ](https://matrix.to/#/#macos:nixos.org )
2023-06-20 14:00:28 +00:00
- @LnL7 on twitter
