Nix Repositories

Nix is a package manager designed to help you create reproducible and isolated builds. JFrog Artifactory supports Nix repositories, enabling you to manage Nix packages and channels in a centralized location. By integrating with Nix, Artifactory acts as a high-performance binary cache (substituter), ensuring reliable, reproducible, and fast builds for your applications.

Artifactory fully supports Nix repositories and enhances the Nix ecosystem with the following capabilities:

• Private Binary Storage: Host and share your own Nix builds internally in local repositories.
• Smart Proxying: Proxy and cache the official Nix registry search.nixos.org with a remote repository to save bandwidth and ensure offline availability.
• Unified Access: Aggregate multiple repositories into a single virtual repository for simplified client configuration.
• Global Distribution: Use Federated repositories to synchronize Nix artifacts across different geographic locations.
• Metadata Calculation: Calculate metadata for Nix packages to enable artifact management and search in Artifactory.

Get Started with Nix

To get started working with Nix, complete the following main steps:

1. Create a Nix repository
2. Connect Nix to Artifactory
3. Deploy and install Nix binaries and channels

Create a Nix Repository

This topic describes how to create a Nix repository. This is required before publishing and installing Nix packages and channels. There are three primary types of repositories:

• Local repositories: Store and share first- and second-party packages with your organization

• Remote repositories: Download packages from search.nixos.org location and other Artifactory instances

• Virtual repositories: Aggregate remote and local repositories, enabling your organization to scale by providing a single URL that provides access to multiple repositories and types

For more information on JFrog repositories, see Repository Management.

Prerequisite: You need Admin or Project Admin permissions in Artifactory to create a repository. If you don't have Admin permissions, the option will not be available.

To create a Nix repository:

1. In the Administration tab, click Repositories > Create a Repository.

   

2. Select the type of repository you want to create.

   📘

   Note

   Artifactory supports federated Nix repositories.

3. Select the Nix package type.

4. Configure the required fields for the repository:

   • For local repositories, in the Repository Key field, type a meaningful name for the repository. For example, nix-local. For more information on local repositories and their settings, see Local Repositories.
   • For remote repositories, verify the Repository URL and update as needed. For more information on remote repositories and their settings, see Remote Repositories.
   • For virtual repositories, select one or more local or remote repository types to include in the virtual repository. For more information on virtual repositories and their settings, see Virtual Repositories.

5. Click Create Repository. The repository is created and the Repositories window is displayed.

Connect Nix to Artifactory

To use Nix with Artifactory, complete the following configurations as needed:

• Configure Binary Cache
• Configure Channels

Prerequisites:

• Nix package manager installed on your local machine or build agent.
• A Nix repository. For more information, see Create a Nix repository.

Configure Binary Cache

To use Artifactory as a binary cache instead of building from source, add it as a substituter in your nix.conf file.

To add Artifactory as a substituter:

1. Open the nix.conf file in a text editor from one of the following locations:

   • For user-specific configuration: ~/.config/nix/nix.conf

   • For system-wide configuration: /etc/nix/nix.conf

     📘

     Note

     Editing system-wide configurations requires root or sudo admin privileges.

2. Add the following line to the nix.conf file:

   TOML

   substituters = https://<USERNAME>:<AUTH>@<JFrogPlatformURL>/artifactory/api/nix/<REPO_NAME>?priority=<PRIORITY_VALUE>

   Where:

   • <USERNAME>: Your Artifactory username

   • <AUTH>: Your Artifactory identity token

   • <JFrogPlatformURL>: Your JFrog Platform URL

   • <REPO_NAME>: The name of the target repository

   • <PRIORITY_VALUE>: The query priority value

     📘

     Note

     Nix resolves dependencies based on priority. A lower value means a higher priority. The public cache cache.nixos.org has a default priority of 40. Set the Artifactory priority a value lower than 40 to make sure Artifactory is queried first.

   For example:

   TOML

   substituters = https://jeffry:[email protected]/artifactory/api/nix/nix-local?priority=20

3. To enable modern CLI functionality, including the nix copy command to deploying packages, add the following snippet to the nix.conf file:

   TOML

   experimental-features = nix-command

4. Save the changes to the file.

5. Reload the Nix daemon to apply the changes:

   Shell

   sudo launchctl kickstart -k system/org.nixos.nix-daemon

Configure Channels

You can configure Nix repositories in Artifactory to proxy nixos channels or publish custom channels.

Publishing and caching channels in Artifactory provides a stable, versioned snapshot of the Nixpkgs ecosystem. The snapshots ensure that developers in your organization resolve dependencies against the same verified set of package expressions.

Using Artifactory to proxy and publish Nix channels safeguards build reproducibility and allows you to roll back or pin environments to specific channel releases even if upstream sources change or become unavailable.

To configure channels to resolve from Artifactory:

1. Run the following command:
   Shell

   nix-channel --add https://<USERNAME>:<AUTH>@<JFrogPlatformURL>/artifactory/api/nix/<REPO_NAME>/channels/<CHANNEL_NAME> <CHANNEL_ALIAS>

   Where:

   • <USERNAME>: Your Artifactory username

   • <AUTH>: Your Artifactory identity token

   • <JFrogPlatformURL>: Your JFrog Platform URL

   • <REPO_NAME>: The name of the target repository

   • <CHANNEL_NAME>: The name of the Nix channel

     📘

     Note

     When working with a remote repository, the <CHANNEL_NAME> value must be an exact match for an official name in the NixOS Channel Registry.

   For example:
   Shell

   nix-channel --add https://jeffry:[email protected]/artifactory/api/nix/nix-remote/channels/nixpkgs-25.11-darwin 25.11-darwin

2. Save the changes to the file.
3. Run this command to update the Nix client:
   Shell

   nix-channel --update

Next steps:

• Deploy Nix Packages
• Install Nix Packages

Deploy Nix Packages

You can perform two kinds of Nix deployments:

• Deploy Nix packages
• Deploy channel expressions

Deploy Nix Packages

Use the nix copy command to push packages from your local store to Artifactory.

To deploy Nix packages:

• Run this command from the location in the directory that includes the .nix file:

  Shell

  nix copy --to "https://<USERNAME>:<AUTH>@<JFrogPlatformURL>/artifactory/api/nix/<REPO_NAME>/" --file <PATH_TO_FILE>.nix

  Where:

  • <USERNAME>: Your Artifactory username
  • <AUTH>: Your Artifactory identity token
  • <JFrogPlatformURL>: Your JFrog Platform URL
  • <REPO_NAME>: The name of the target repository
  • <PATH_TO_FILE>: The path to the Nix package file on your local machine

  For example:

  Shell

  nix copy --to "https://jeffry:[email protected]/artifactory/api/nix/nix-local/" nix-package/default.nix

Deploy Channel Expressions

You can deploy a channel expression to Artifactory by using a curl PUT request.

📘

Note

The source file name must be named nixexprs.tar.xz. This name is mandatory and enforced. The Nix client specifically looks for this filename to resolve the channel expressions.

To deploy a channel expression:

• Run this command:

  Shell

  curl -X PUT -u <USERNAME>:<AUTH> -T nixexprs.tar.xz https://<JFrogPlatformURL>/artifactory/api/nix/<REPO_NAME>/channels/<CHANNEL_NAME>/<NIX_FLAVOR>/<SNAPSHOT_IDENTIFIER>

  Where:

  • <USERNAME>: Your Artifactory username
  • <AUTH>: Your Artifactory identity token
  • <JFrogPlatformURL>: Your JFrog Platform URL
  • <REPO_NAME>: The name of the target repository
  • <CHANNEL_NAME>: The name of the channel
  • <NIX_FLAVOR>: The distribution or flavor of Nix. Potential values are:
    • nixpkgs
    • nixos
  • <SNAPSHOT_IDENTIFIER>: The snapshot identifier

  For example:

  Shell

  nix copy --to "https://jeffry:[email protected]/artifactory/api/nix/nix-local/" nix-package/default.nix

Install Nix Packages

You can install Nix packages from Artifactory using one of the following supported methods:

• nix-env
• nix-shell
• NixOS Configuration

Install Nix packages with nix-env

To install Nix packages with nix-env:

• Run the following command:
  Shell

  nix-env -iA nixpkgs.<PACKAGE_NAME>

  Where <PACKAGE_NAME> is the name of the Nix package. For example:
  Shell

  nix-env -iA nixpkgs.neovim

Install Nix packages with nix-shell

To install Nix packages with nix-shell:

• Run the following command:
  Shell

  nix-shell -p <PACKAGE_NAME>

  Where <PACKAGE_NAME> is the name of the Nix package. For example:
  Shell

  nix-shell -p neovim

Install Nix packages with NixOS Configuration

To install Nix packages with NixOS Configuration:

1. Open the /etc/nixos/configuration.nix file in a text editor.
2. Add the following snippet to the file:

   environment.systemPackages = [ 
       pkgs.<PACKAGE_NAME>
   ];

   Where <PACKAGE_NAME> is the name of the Nix package. For example:

   environment.systemPackages = [ 
       pkgs.neovim
   ];

3. Save the changes to the file.

Additional Nix Information

The following topics provide additional information about working with Nix repositories in Artifactory.

• Nix Package Identification
• Best Practices for Nix Naming and Versioning
• Nix Authentication

Nix Package Identification

This section provides information on how Artifactory identifies and presents Nix package information. Artifactory provides native support for caching and aggregating Nix packages.

Artifactory follows a best-effort aggregation model when presenting packages and versions in the UI and APIs. This means that instead of exposing every build artifact as a separate package, Artifactory groups related artifacts together to provide a more natural browsing and discovery experience. This approach balances typical package searching workflows with Nix system compatibility.

How Artifactory Identifies Nix Packages

To identify and group packages, Artifactory extracts the following package metadata from the Nix narInfo metadata:

• The Nix store path (storePath)
• The name and version encoded in that path

This information populates the Packages view, where you can browse packages by name, see how many versions are available, and identify the latest available version. For more information, see Viewing Packages.

📘

Note

The Packages page is designed for browsing available packages, understanding what software exists in a repository, identifying commonly used versions, and high-level visibility across repositories.

It is not intended to replace Nix's native mechanisms for reproducible builds, dependency planning, or cryptographic identity guarantees.

Why Store Hash Isn't the Primary Package Identity

Nix packages are fundamentally content-addressed. Each build output has a unique store path hash derived from all of its inputs. While this guarantees correctness and reproducibility, using the store hash as the primary identity would have significant drawbacks for aggregation in Artifactory:

• Every rebuild, even with minimal changes, would appear as a new package
• The number of visible packages would grow exponentially
• Significant negative impacts on discoverability
• Browsing by “logical package” (for example, Firefox) would be impractical

Because of these implications, Artifactory does not treat each store hash as a separate package entry. Instead, the system groups artifacts using the extracted name and version information to provide a usable catalog.

Best Practices for Nix Naming and Versioning

The following are best practices when publishing Nix packages with full control over naming and versioning:

• Use a stable and explicit package name.
• Avoid toolchain or runtime identifiers in the name.
• Use clean and predictable version string.
• Where possible, use semantic versioning.
• Avoid embedding branch names, dates, or commit hashes directly in the version.
• Encode build or revision metadata separately.
• Maintain consistent naming across releases.

These practices are recommended to improve aggregation accuracy and discoverability in Artifactory.

Nix Authentication

The Nix client does not provide interactive authentication prompts. To authenticate with Artifactory, you must provide credentials using one of the following methods:

• Credentials in URL (Recommended): Embed credentials directly in the repository URL using the format https://<USERNAME>:<AUTH>@<JFrogPlatformURL>/<REPO_NAME>.
• .netrc File: Add your Artifactory credentials to ~/.config/nix/nix.conf or /etc/nix/nix.conf to authenticate to Artifactory as a binary.
• access-tokens: Pass authentication against APIs when performing fetch operations like fetchTarball or fetchurl from a .nix file.
  • CLI:
    Shell

    nix build . --option access-tokens "github.com=$<GITHUB_TOKEN>"

  • In nix.conf:

    "
    access-tokens = github.com=ghp_<TOKEN> gitlab.com=glpat_<TOKEN>
      "

  To authenticate to Artifactory as a binary cache or for generic file hosting, you still need to use the .netrc method.

Nix Limitations in Artifactory

The following are the limitations of Nix repositories in Artifactory:

• Registry Browsing: Artifactory doesn't support browsing the contents of remote Nix registries via UI. Only artifacts that have been explicitly pulled or deployed will appear in the artifact tree.
• Authentication: The Nix client does not provide interactive authentication prompts. For more information about authentication options, see Nix Authentication.
• Version extraction: The following are limitations related to Nix package version extraction.

  • Free-form version strings: Nix does not enforce a strict versioning standard. Version strings may include numbers, dates, channel or branch identifiers, or Git-derived identifiers. Free-form versioning has the following impact on Nix packages in Artifactory:

    • Versions may not follow semantic versioning
    • Version ordering may not reflect chronological or functional precedence
    • The "latest version” is best-effort metadata, not an authoritative identifier

  • Duplicate or ambiguous versions: In cases of duplicate or ambiguous versions, Artifactory aggregates packages based on the extracted version value and does not attempt to differentiate further at the package level.

    Examples of duplicate or ambiguous versions are the same version string appearing multiple times, different builds with the same extracted version, or patch-level changes that are indistinguishable at the version string level.

• Name extraction: The displayed package name may not match the name used with nix install for the following reasons.
  • Toolchain and runtime prefixes: The extracted package name may include store path prefixes from language-based or toolchain-based build tools.
  • Package name overrides: Some Nix derivations explicitly override the package name (pname) value during evaluation, and the store path may still reflect intermediate or contextual naming.