{"id":28069798,"url":"https://github.com/chingc/tutorial-nix","last_synced_at":"2025-08-16T16:03:37.358Z","repository":{"id":239078969,"uuid":"798468418","full_name":"chingc/tutorial-nix","owner":"chingc","description":"A quickstart and reference for Nix to help you get up and running fast.","archived":false,"fork":false,"pushed_at":"2025-05-06T16:32:54.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-16T16:02:12.635Z","etag":null,"topics":["documentation","nix","quickstart","readme","reference","tutorial"],"latest_commit_sha":null,"homepage":"https://nixos.org","language":null,"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/chingc.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}},"created_at":"2024-05-09T20:54:00.000Z","updated_at":"2025-05-06T16:33:00.000Z","dependencies_parsed_at":"2024-05-15T14:29:32.127Z","dependency_job_id":"71568b73-d79c-489f-adf6-3f4f334b7a86","html_url":"https://github.com/chingc/tutorial-nix","commit_stats":{"total_commits":2,"total_committers":1,"mean_commits":2.0,"dds":0.0,"last_synced_commit":"d184274c25a2edf072bfc8af83feae4132d1d096"},"previous_names":["chingc/docs-nix","chingc/quickstart-nix","chingc/readme-nix","chingc/tutorial-nix"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chingc/tutorial-nix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chingc%2Ftutorial-nix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chingc%2Ftutorial-nix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chingc%2Ftutorial-nix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chingc%2Ftutorial-nix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chingc","download_url":"https://codeload.github.com/chingc/tutorial-nix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chingc%2Ftutorial-nix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270734952,"owners_count":24636271,"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","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["documentation","nix","quickstart","readme","reference","tutorial"],"created_at":"2025-05-12T19:14:59.900Z","updated_at":"2025-08-16T16:03:37.079Z","avatar_url":"https://github.com/chingc.png","language":null,"readme":"# README: Nix\n\nHello, this is a record of my journey learning [Nix](https://nixos.org).\n\nI'm writing this mainly as a quickstart and reference for my future self, but I hope others find it helpful.\n\nThis is not comprehensive. It will just go over the basics and some of the more useful features.\n\nNote: This doc will be using the newer `nix` cli interface and flakes.\n\n## What is it?\n\nNix is a purely functional package manager. It helps to avoid the installation and versioning pain points of software development.\n\nThat doesn't sound like much. However...\n\nSuppose you need golang, node, and python. You can create a shell environment that has those tools with a single command.\n\n```bash\n$ go; node; python\nzsh: command not found: go\nzsh: command not found: node\nzsh: command not found: python\n\n$ nix shell nixpkgs#go nixpkgs#nodejs nixpkgs#python3\n\n$ go version\ngo version go1.23.3 darwin/arm64\n\n$ node --version\nv20.18.0\n\n$ python --version\nPython 3.12.7\n\n$ exit\n\n$ go; node; python\nzsh: command not found: go\nzsh: command not found: node\nzsh: command not found: python\n```\n\nWe were able to get access to golang, node, and python instantly. Actually, the initial run takes a few moments, but subsequent runs are fast!\n\nWe skipped the setup docs, we didn't edit our shell profile, and we didn't have to worry about `PATH` or other environment variables.\n\nBest of all, we didn't pollute the user environment. Everything is gone once you `exit` or `Ctrl-D` the shell.\n\nOther benefits?\n\nNix builds packages in isolation from each other. This ensures that they are reproducible and don't have undeclared dependencies, so if a package works on one machine, it will also work on another.\n\nNix makes it trivial to share development and build environments for your projects, regardless of what programming languages and tools you're using.\n\n## Install\n\nThe easiest way to install Nix (Linux, macOS, WSL2) is to use [The Determinate Nix Installer](https://zero-to-nix.com/concepts/nix-installer).\n\nIt installs Nix with flake support and the unified CLI feature already enabled. It also stores a receipt for the install process to allow for a clean uninstall.\n\nNote: Directions to upgrade or uninstall can be found in their [GitHub repo](https://github.com/DeterminateSystems/nix-installer).\n\n## Run Programs Directly\n\nWe've already seen how a shell environment can be created with `nix shell`.\n\nWith `nix run` we can skip creating the shell and run programs directly.\n\n```bash\n$ nix run nixpkgs#cowsay Hello, Nix!\n\n$ nix run nixpkgs#lolcat -- --help\n\n$ nix run nixpkgs#fortune | nix run nixpkgs#lolcat\n```\n\n## Reproducible Scripts\n\nA trivial script with non-trivial dependencies.\n\n```bash\n#! /bin/bash\n\ncurl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .\n```\n\nThis script fetches XML content from a URL, converts it to JSON, and formats it for better readability.\n\nIt requires curl, xml2json, jq, and bash. If any of these dependencies are not present on the system running the script, it will fail partially or altogether.\n\nWith Nix, we can declare all dependencies explicitly, and produce a script that will always run on any machine that has Nix.\n\n```bash\n#! /usr/bin/env nix\n#! nix shell nixpkgs#bash nixpkgs#curl nixpkgs#jq nixpkgs#python312Packages.xmljson\n#! nix --ignore-environment --command bash\n\ncurl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .\n```\n\n- The `--ignore-environment` option prevents the script from implicitly using programs that may already exist on the system.\n- The `--command` option specifies the interpreter that will be invoked by nix shell after it has obtained the dependencies and initialized the environment.\n\nNotice how `nix shell` was only specified once when using multiple nix shell shebangs.\n\nAs long as the system has Nix, scripts can be written in any language without worrying about dependencies.\n\n```bash\n#! /usr/bin/env nix\n#! nix shell nixpkgs/nixos-24.11#python3\n#! nix --ignore-environment --command python\n\nprint(\"n\", \"n^2\")\nfor n in range(1, 10):\n    print(n, n * n)\n```\n\nIn this example we've specified the `nixos-24.11` stable channel. This helps reproducibility. You can even use a git commit hash of the Nixpkgs repository for further granularity.\n\n## Declarative Shell Environments\n\nWe can create a file that defines an environment. This can be shared with anyone to recreate the same environment on a different machine.\n\nCreate a `flake.nix` file:\n\n```\n{\n    description = \"A fun shell environment\";\n\n    inputs = {\n        nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n        flake-utils.url = \"github:numtide/flake-utils\";\n    };\n\n    outputs = { self, nixpkgs, flake-utils }:\n        flake-utils.lib.eachDefaultSystem (system:\n            let\n                pkgs = import nixpkgs { inherit system; config = {}; overlays = []; };\n            in {\n                devShells.default = pkgs.mkShellNoCC {\n\n                    # Packages to include\n                    packages = with pkgs; [\n                        cowsay\n                        lolcat\n                        python3Full\n                    ];\n\n                    # Define environment variables\n                    env = {\n                        GREETING = \"Hello, Nix!\";\n                    };\n\n                    # Run a shell script on environment startup\n                    shellHook = ''\n                        echo $GREETING | cowsay | lolcat\n                    '';\n\n                };\n            }\n        );\n}\n```\n\nEnter the environment by running `nix develop` in the same directory as `flake.nix`.\n\nNote: If the directory you're working in is a git repository you may get an error indicating `flake.nix` doesn't exist. Stage the file with `git add` to get nix to recognize it. I don't know. It's weird like that.\n\nIf you make changes to `flake.nix` just `exit` or `Ctrl-D` to exit the environment and restart it with `nix develop`.\n\n## More on Versioning\n\nWithout pinning or locking your tools and dependencies to specific versions you'll eventually hit the point of development where a bug is affecting others but somehow it \"works on my machine\". It's often very unpleasant and very difficult to debug.\n\nWe've seen from an earlier example how to pin to a specific Nix channel. The channels can be found at [status.nixos.org](https://status.nixos.org).\n\nTip: [Which channel branch should I use?](https://nix.dev/concepts/faq#which-channel-branch-should-i-use)\n\n## Search for Packages\n\nGo to \u003chttps://search.nixos.org/packages\u003e or use the command line.\n\n```bash\n$ nix search nixpkgs neovim\n```\n\n#### Wrapped vs Unwrapped\n\nThe key difference between wrapped and unwrapped packages in NixOS is that wrapped packages are configured to work seamlessly within the NixOS environment, while unwrapped packages are the raw, unmodified versions.\n\nIn most cases, users should install the wrapped version of a package, as it is preconfigured to work correctly on NixOS. The unwrapped version is primarily used when further customization or overriding of the package is required, as it serves as the base for creating a new wrapped derivation with additional modifications.\n\n## Thoughts\n\ntbd\n\n## References\n\nBelow are some of the main sources I've used.\n\n- [GitHub: DeterminateSystems/nix-installer](https://github.com/DeterminateSystems/nix-installer)\n- [GitHub: NixOS/nix](https://github.com/NixOS/nix)\n- [GitHub: NixOS/nixpkgs](https://github.com/NixOS/nixpkgs)\n- [Nix Reference Manual: nix run](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-run)\n- [Nix Reference Manual: nix search](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-search)\n- [Nix Reference Manual: nix shell](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-env-shell)\n- [nix.dev](https://nix.dev)\n- [nix.dev: Best Practices](https://nix.dev/guides/best-practices)\n- [Zero to Nix](https://zero-to-nix.com)\n\nAdditional resources:\n\n- [Kubukoz Blog: Nix Flakes First Steps](https://blog.kubukoz.com/flakes-first-steps/)\n- [Nix Package Versions](https://lazamar.co.uk/nix-versions/)\n- [NixOS Hydra](https://hydra.nixos.org)\n- [NixOS Learn](https://nixos.org/learn)\n- [NixOS Search Packages](https://search.nixos.org/packages)\n- [NixOS Status](https://status.nixos.org)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchingc%2Ftutorial-nix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchingc%2Ftutorial-nix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchingc%2Ftutorial-nix/lists"}