Syncing iCloud contacts in Thunderbird on NixOS and Home-Manager (25.05)

I haven’t been much of a distro hopper, but NixOS caught my attention after working several years with a popular rolling release based distro which I’ve also grown very fond of.

Basic NixOS setup has been fairly straight forward for me; And though I still have wide gaps I fill on a bi-daily basis, my system does not slow me down in daily business.

Todays micro-journey has been about contacts in Thunderbird and how to extract the correct carddav URL from iCloud.

Other tutorials I found from last year explain how to inspect network traffic on icloud.com and how to transform the found URL. Not only did this not work for me anymore, but since addressbook discovery now works properly between TB and apple I found it worthwhile to document this easier way.

This article is my first and is supposed to be a brief step-by-step guide as the most efficient setup path has changed in the last year and other docs I found were outdated. Let me know if there’s anything unclear, I hope this helps others and me in the future to grasp how I extracted the apple details and set this up in general.

(1/3) Authentication

There are three problems to overcome, the first is the authentication. Apple encourages 2FA, which does not work well with Thunderbird, which you expect to just show your contacts.

Apple provides a solution for Application which request such data on your behalve: App-Specific Passwords.

The concept is simple: While you log in with your regular password and 2FA, Thunderbird gets its own password and is exempt from 2FA.

Login at https://account.apple.com/account/manage and on the bottom right choose App-Specific Passwords. Click the blue plus sign to generate a new app-specific password. Choose a proper name to identify it in the long run, such as Thunderbird NixOS. It’s possible you have to enter your regular password again to make sure it’s you at this point.

The should now be a generated password, which you store in the password manager of your choice to not lose it, as you wont be able to read it again later on this page.

Close the account page and logout, as we’re done with the first of three problems.

(2/3) Extraction of the CardDAV URL

The second problem (and the reason to write this guide in 2025) is the new way to extract cardbook addresses.

In the third and last section we will persist the data we found in this one using a home-manager configuration, but for now we play dumb and do the following manually:

Launch Thunderbird and while in the contacts tab click Create a new address book left to the big blue “New Contact”-button on the top left of the page.

Choose Add CardDAV Addressbook. For the username use your regular Apple ID, e.g. your-username@icloud.com. Depending on your settings this might just be your regular email-Address, in either case: it’s what you used to login in to apple in the first section.

For the URL use this generic one, which we’ll use to get the correct one: https://contacts.icloud.com/contacts/

As the password you use the App-Specific password you generated in the last section. Do NOT use your regular Apple-Account password.

If everything went well, Thunderbird now detects the available address book in your iCloud account called card.

Complete the process and right click this new card address book to read its properties.

The URL of it should be way longer than what you entered previously. Note it down somewhere to use it in the last of the three sections to persist the account in your NixOS/Home-Manager configuration.

(3/3) NixOS Home-Manager configuration

I’ll provide an exemplary Home-Manager configuration, as you want your addressbook available for your user but not every other.

This tutorial does not go into to pros and cons of Home-Manager, there is enough material out there for you to evaluate them on your own.

NixOS is configured using Nix, and there’s a section accounts.contact, which we can then fill like this with your previously fetched details. Make sure to replace both the url and the *userName* completely and not just the number section in it, as the subdomain might differ as well.

accounts.contact.accounts."iCloud.com" = {
    remote = {
      type = "carddav";
      url = "https://p33-contacts.icloud.com/133700042/carddavhome/card/";
      userName = "your-username@icloud.com";
    };
  };

sadly Thunderbird does not respect this section as of now (NixOS 25.05). To complete the setup we add another section under programs.thunderbird like this:

thunderbird = {
      enable = true;
      settings =
        let
          safeName = builtins.replaceStrings [ "." ] [ "-" ];
          contactsAccount = config.accounts.contact.accounts."iCloud.com";
          contactsAccountSafeName = safeName contactsAccount.name;
          addressBookFilename = "abook-${contactsAccountSafeName}.sqlite";
        in
          {
            "ldap_2.servers.${contactsAccountSafeName}.carddav.url" = contactsAccount.remote.url;
            "ldap_2.servers.${contactsAccountSafeName}.carddav.username" = contactsAccount.remote.userName;
            "ldap_2.servers.${contactsAccountSafeName}.description" = contactsAccount.name;
            "ldap_2.servers.${contactsAccountSafeName}.dirType" = 102;
            "ldap_2.servers.${contactsAccountSafeName}.filename" = addressBookFilename;
            "mail.collect_addressbook" = "jscarddav://${addressBookFilename}";
          };
    };

I won’t go into the details of the language here, but what we effectively do is to create a Thunderbird specific configuration with an escaped name of the account based on the section we added previously. This way, when we alter the standardized previous section, this one will update accordingly.

In case you start using a different addressbook software, chance are high the accounts show up without further setup, and in the future, once the respective issue is resolved, this latter section can be safely removed even for Thunderbird.

Closing words

In order to apply this configuration to your system, you need to rebuild it. As I said earlier my experience is limited, but I’d suggest e.g. this line to do it after closing related programs like Thunderbird.

nixos-rebuild switch --use-remote-sudo

If everything went well, you should be able to open Thunderbird again and see a new address book called “iCloud.com”.

At this point you can clean up and remove the previously created addressbook called card.

Troubleshooting

If nothing appears in the addressbook right click it to synchronize.

In Thunderbird only use the App-Specific password from section two.

Debugging Nix might appear cumbersome. As a general rule of thumb, the problems in Nix stacktraces are the most detailed at the bottom. Read thoroughly and stay patient, I feel like it’s worth the hassle.

Good luck and thanks for reading :)