{"id":13647677,"url":"https://github.com/nix-community/nix-direnv","last_synced_at":"2025-05-14T04:07:38.497Z","repository":{"id":37012815,"uuid":"211264092","full_name":"nix-community/nix-direnv","owner":"nix-community","description":"A fast, persistent use_nix/use_flake implementation for direnv [maintainer=@Mic92 / @bbenne10] ","archived":false,"fork":false,"pushed_at":"2025-05-08T00:32:28.000Z","size":640,"stargazers_count":2157,"open_issues_count":9,"forks_count":115,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-08T01:29:02.097Z","etag":null,"topics":["hacktoberfest","managed-by-renovate","nix-community-buildbot"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nix-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"nix-community"}},"created_at":"2019-09-27T07:43:47.000Z","updated_at":"2025-05-06T16:21:51.000Z","dependencies_parsed_at":"2024-01-29T02:41:52.940Z","dependency_job_id":"3b047c96-fffb-4a43-a0e8-fa1f077a9db3","html_url":"https://github.com/nix-community/nix-direnv","commit_stats":{"total_commits":566,"total_committers":70,"mean_commits":8.085714285714285,"dds":0.6007067137809188,"last_synced_commit":"0d71ed4c4e98918e79bec02be48a66756a393884"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnix-direnv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnix-direnv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnix-direnv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnix-direnv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nix-community","download_url":"https://codeload.github.com/nix-community/nix-direnv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253831891,"owners_count":21971176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","managed-by-renovate","nix-community-buildbot"],"created_at":"2024-08-02T01:03:42.185Z","updated_at":"2025-05-14T04:07:38.466Z","avatar_url":"https://github.com/nix-community.png","language":"Shell","funding_links":["https://opencollective.com/nix-community"],"categories":["nix","Shell","Python","Development","Nix"],"sub_categories":["Kubernetes","Discovery"],"readme":"# nix-direnv\n\n![Test](https://github.com/nix-community/nix-direnv/workflows/Test/badge.svg)\n\nA faster, persistent implementation of `direnv`'s `use_nix` and `use_flake`, to\nreplace the built-in one.\n\nProminent features:\n\n- significantly faster after the first run by caching the `nix-shell`\n  environment\n- prevents garbage collection of build dependencies by symlinking the resulting\n  shell derivation in the user's `gcroots` (Life is too short to lose your\n  project's build cache if you are on a flight with no internet connection)\n\n## Why not use `lorri` instead?\n\nCompared to [lorri](https://github.com/nix-community/lorri), nix-direnv is\nsimpler (and requires no external daemon). Additionally, lorri can sometimes\nre-evaluate the entirety of nixpkgs on every change (leading to perpetual high\nCPU load).\n\n## Installation\n\n\u003e [!WARNING]\\\n\u003e We assume that [direnv](https://direnv.net/) is installed properly because\n\u003e nix-direnv IS NOT a replacement for regular direnv _(only some of its\n\u003e functionality)_.\n\n\u003e [!NOTE]\\\n\u003e nix-direnv requires a modern Bash. MacOS ships with bash 3.2 from 2007. As a\n\u003e work-around we suggest that macOS users install `direnv` via Nix or Homebrew.\n\u003e There are different ways to install nix-direnv, pick your favourite:\n\n\u003cdetails\u003e\n  \u003csummary\u003e Via home-manager (Recommended)\u003c/summary\u003e\n\n### Via home-manager\n\nNote that while the home-manager integration is recommended, some use cases\nrequire the use of features only present in some versions of nix-direnv. It is\nmuch harder to control the version of nix-direnv installed with this method. If\nyou require such specific control, please use another method of installing\nnix-direnv.\n\nIn `$HOME/.config/home-manager/home.nix` add\n\n```Nix\n{\n  # ...other config, other config...\n\n  programs = {\n    direnv = {\n      enable = true;\n      enableBashIntegration = true; # see note on other shells below\n      nix-direnv.enable = true;\n    };\n\n    bash.enable = true; # see note on other shells below\n  };\n}\n```\n\nCheck the current\n[Home Manager Options](https://mipmip.github.io/home-manager-option-search/?query=direnv)\nfor integration with shells other than Bash. Be sure to also allow\n`home-manager` to manage your shell with `programs.\u003cyour_shell\u003e.enable = true`.\n\n\u003c/details\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eDirenv's source_url\u003c/summary\u003e\n\n### Direnv source_url\n\nPut the following lines in your `.envrc`:\n\n```bash\nif ! has nix_direnv_version || ! nix_direnv_version 3.0.7; then\n  source_url \"https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.7/direnvrc\" \"sha256-bn8WANE5a91RusFmRI7kS751ApelG02nMcwRekC/qzc=\"\nfi\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eVia system configuration on NixOS\u003c/summary\u003e\n\n### Via system configuration on NixOS\n\nFor NixOS 23.05+ all that's required is\n\n```Nix\n{\n  programs.direnv.enable = true;\n}\n```\n\nother available options are:\n\n```Nix\n{ pkgs, ... }: {\n  #set to default values\n  programs.direnv = {\n    package = pkgs.direnv;\n    silent = false;\n    loadInNixShell = true;\n    direnvrcExtra = \"\";\n    nix-direnv = {\n      enable = true;\n      package = pkgs.nix-direnv;\n    };\n  }\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWith `nix profile`\u003c/summary\u003e\n\n### With `nix profile`\n\nAs **non-root** user do the following:\n\n```shell\nnix profile install nixpkgs#nix-direnv\n```\n\nThen add nix-direnv to `$HOME/.config/direnv/direnvrc`:\n\n```bash\nsource $HOME/.nix-profile/share/nix-direnv/direnvrc\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eFrom source\u003c/summary\u003e\n\n### From source\n\nClone the repository to some directory and then source the direnvrc from this\nrepository in your own `~/.config/direnv/direnvrc`:\n\n```bash\n# put this in ~/.config/direnv/direnvrc\nsource $HOME/nix-direnv/direnvrc\n```\n\n\u003c/details\u003e\n\n## Usage example\n\nEither add `shell.nix` or a `default.nix` to the project directory:\n\n```nix\n# save this as shell.nix\n{ pkgs ? import \u003cnixpkgs\u003e {}}:\n\npkgs.mkShell {\n  packages = [ pkgs.hello ];\n}\n```\n\nThen add the line `use nix` to your envrc:\n\n```shell\necho \"use nix\" \u003e\u003e .envrc\ndirenv allow\n```\n\nIf you haven't used direnv before, make sure to\n[hook it into your shell](https://direnv.net/docs/hook.html) first.\n\n### Using a non-standard file name\n\nYou may use a different file name than `shell.nix` or `default.nix` by passing\nthe file name in `.envrc`, e.g.:\n\n```shell\necho \"use nix foo.nix\" \u003e\u003e .envrc\n```\n\n## Flakes support\n\nnix-direnv also comes with an alternative `use_flake` implementation. The code\nis tested and does work but the upstream flake api is not finalized, so we\ncannot guarantee stability after a nix upgrade.\n\nLike `use_nix`, our `use_flake` will prevent garbage collection of downloaded\npackages, including flake inputs.\n\n### Creating a new flake-native project\n\nThis repository ships with a\n[flake template](https://github.com/nix-community/nix-direnv/tree/master/templates/flake).\nwhich provides a basic flake with devShell integration and a basic `.envrc`.\n\nTo make use of this template, you may issue the following command:\n\n```shell\nnix flake new -t github:nix-community/nix-direnv \u003cdesired output path\u003e\n```\n\n### Integrating with a existing flake\n\n```shell\necho \"use flake\" \u003e\u003e .envrc \u0026\u0026 direnv allow\n```\n\nThe `use flake` line also takes an additional arbitrary flake parameter, so you\ncan point at external flakes as follows:\n\n```bash\nuse flake ~/myflakes#project\n```\n\n### Advanced usage\n\n#### use flake\n\nUnder the covers, `use_flake` calls `nix print-dev-env`. The first argument to\nthe `use_flake` function is the flake expression to use, and all other arguments\nare proxied along to the call to `print-dev-env`. You may make use of this fact\nfor some more arcane invocations.\n\nFor instance, if you have a flake that needs to be called impurely under some\nconditions, you may wish to pass `--impure` to the `print-dev-env` invocation so\nthat the environment of the calling shell is passed in.\n\nYou can do that as follows:\n\n```shell\necho \"use flake . --impure\" \u003e .envrc\ndirenv allow\n```\n\n#### use nix\n\nLike `use flake`, `use nix` now uses `nix print-dev-env`. Due to historical\nreasons, the argument parsing emulates `nix shell`.\n\nThis leads to some limitations in what we can reasonably parse.\n\nCurrently, all single-word arguments and some well-known double arguments will\nbe interpreted or passed along.\n\n#### Manual reload of the nix environment\n\nTo avoid delays and time consuming rebuilds at unexpected times, you can use\nnix-direnv in the \"manual reload\" mode. nix-direnv will then tell you when the\nnix environment is no longer up to date. You can then decide yourself when you\nwant to reload the nix environment.\n\nTo activate manual mode, use `nix_direnv_manual_reload` in your `.envrc` like\nthis:\n\n```shell\nnix_direnv_manual_reload\nuse nix # or use flake\n```\n\nTo reload your nix environment, use the `nix-direnv-reload` command:\n\n```shell\nnix-direnv-reload\n```\n\n##### Known arguments\n\n- `-p`: Starts a list of packages to install; consumes all remaining arguments\n- `--include` / `-I`: Add the following path to the list of lookup locations for\n  `\u003c...\u003e` file names\n- `--attr` / `-A`: Specify the output attribute to utilize\n\n`--command`, `--run`, `--exclude`, `--pure`, `-i`, and `--keep` are explicitly\nignored.\n\nAll single word arguments (`-j4`, `--impure` etc) are passed to the underlying\nnix invocation.\n\n#### Tracked files\n\nAs a convenience, `nix-direnv` adds common files to direnv's watched file list\nautomatically.\n\nThe list of additionally tracked files is as follows:\n\n- for `use nix`:\n  - `~/.direnvrc`\n  - `~/.config/direnv/direnvrc`\n  - `.envrc`,\n  - A single nix file. In order of preference:\n    - The file argument to `use nix`\n    - `default.nix` if it exists\n    - `shell.nix` if it exists\n\n- for `use flake`:\n  - `~/.direnvrc`\n  - `~/.config/direnv/direnvrc`\n  - `.envrc`\n  - `flake.nix`\n  - `flake.lock`\n  - `devshell.toml` if it exists\n\nUsers are free to use direnv's builtin `watch_file` function to track additional\nfiles. `watch_file` must be invoked before either `use flake` or `use nix` to\ntake effect.\n\n#### Environment Variables\n\nnix-direnv sets the following environment variables for user consumption. All\nother environment variables are either a product of the underlying nix\ninvocation or are purely incidental and should not be relied upon.\n\n- `NIX_DIRENV_DID_FALLBACK`: Set when the current revision of your nix shell or\n  flake's devShell are invalid and nix-direnv has loaded the last known working\n  shell.\n\nnix-direnv also respects the following environment variables for configuration.\n\n- `NIX_DIRENV_FALLBACK_NIX`: Can be set to a fallback Nix binary location, to be\n  used when a compatible one isn't available in `PATH`. Defaults to\n  `config.nix.package` if installed via the NixOS module, otherwise needs to be\n  set manually. Leave unset or empty to fail immediately when a Nix\n  implementation can't be found on `PATH`.\n\n## General direnv tips\n\n- [Changing where direnv stores its cache][cache_location]\n- [Quickly setting up direnv in a new nix project][new_project]\n- [Disable the diff notice (requires direnv 2.34+)][hide_diff_notice]: Note that\n  this goes into direnv's TOML configuration!\n\n[cache_location]: https://github.com/direnv/direnv/wiki/Customizing-cache-location\n[new_project]: https://github.com/nix-community/nix-direnv/wiki/Shell-integration\n[hide_diff_notice]: https://direnv.net/man/direnv.toml.1.html#codehideenvdiffcode\n\n## Other projects in the field\n\n- [lorri](https://github.com/nix-community/lorri)\n- [sorri](https://github.com/nmattia/sorri)\n- [nixify](https://github.com/kalbasit/nur-packages/blob/master/pkgs/nixify/envrc)\n- [lorelei](https://github.com/shajra/direnv-nix-lorelei)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnix-direnv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnix-community%2Fnix-direnv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnix-direnv/lists"}