rhelmot blog2026-08-29 00:00-0700It's a python module world, we're just living in it2026-08-29 00:00-0700How the import statement and the python module system interact

I have spent the better part of 14 years writing Python for fun and profit. I don’t recommend anyone does this, especially if you’re just starting off learning to program, but (joker voice) we live in a society, so it falls on our shoulders to explain how to do this effectively.

Theimport statement is the powerhouse of the Python ecosystem. You categorically need it or something like it if you’re going to do anything complicated in the language. Unfortunately, it has some deeply unintuitive characteristics which I struggled with for a long time and which I have struggled to explain to my peers and pupils. This post attempts to de-mystify what happens when you type this out.

The environment variablePYTHONPATH controls where Python will look for crap when you give it an unqualified import statement. Valid python modules are:

1) a .py file, wherein you can importfoo.py withimport foo or, 2) a directory with an__init__.py file, wherein you can importfoo/__init__.py withimport foo, and, 3) some more bullshit that doesn’t matter

The import statement and its cousin, the from-import statement, do two things:

1) they perform the actual import operation which involves crawling the filesystem for code files and executing them to generate module objects in memory, and, 2) they take some aspect of the result of that operation and assigns one or more variables to the current namespace (the one in which you actually typed the import statement).

These two phases are best explained separately, but they are part of the same statement and thus have some odd interactions. Let’s look at them one at a time.

Thing 1: find it and run it

Thexxx inimport xxx orfrom xxx import whatever is thespecification for the first part of this process. When you ask the Python interpreter to do this, it will start looking through all the directories named on$PYTHONPATH (which often includes the current working directory) and scan for anxxx.py orxxx/__init__.py. This file becomes the target of the import. If you sayimport xxx.yyy orfrom xxx.yyy import whatever, then it will be looking forxxx/yyy.py orxxx/yyy/__init__.py.

If you’re already inside some sort of module when you type the import statement, you gain access to relative imports. These start with a dot. Some examples:

  • if you’re inxxx/yyy.py you can sayfrom . import whatever and this will refer toxxx/__init__.py
  • if you sayfrom .zzz import whatever it will refer toxxx/zzz.py orxxx/zzz/__init__.py

You can use two dots to go up a level and so forth:

  • while you’re inxxx/yyy/zzz.py you can sayfrom ..aaa import whatever and will refer toxxx/aaa.py orxxx/aaa/__init__.py
  • you can even sayfrom ..aaa.bbb import whatever and it will refer toxxx/aaa/bbb.py orxxx/aaa/bbb/__init__.py.

Note that becausexxx/yyy.py can do things with these relative imports, it doesn’t make sense to try to run it until Python has successfully executed/loadedxxx/__init__.py. It’ll do this automatically in the background if it needs to.

This reveals something interesting about the Python module system - you don’t necessarily have to import a whole package all at once, and some packages in fact want you to pick and choose which parts you import! If youpip install sillylib and that causessilly/__init__.py shows up on your$PYTHONPATH, even ifsilly/billy.pyalso shows up on$PYTHONPATH, you may not be able to sayimport silly and then accesssilly.billy! This depends on whethersilly/__init__.py actually includes afrom . import billy. It may omit this on purpose! In this case, you will need to explicitly sayimport silly.billy.

Thing 2: mess with the current namespace

Python modules, from a post-import usage perspective, are just objects. If you write a filefoo.py that containsx = 42, you can sayimport foo and then accessfoo.x. The actual mechanics of this is thatfoo in the current namespace, that is, the place you actually typedimport foo, has had a varible bound in it with namefoo that points to the module object which results from executingfoo.py and gathering up all its assignments.

That’s the plainimport xxx statement. When you sayfrom foo import x, it’ll load the module associated with the name “foo”, grab the attributex out of that module, and then assign that to the namex in the current namespace. Theas clause, which we have not mentioned so far in this tutorial but you may have seen before in the wild, adjusts this behavior - you can sayimport foo as foo2 orfrom foo import x as blah to change which name the module or value-within-module gets bound to in the current namespace.

Horrifyingly, there is one very stupid edge case to how these two phases interact. When you use a dotted import path in the plainimport xxx.yyy statement, it will actually put justxxx into your namespace and instead putyyy as an attribute of xxx, in order to satisfy the case we talked about earlier wheresilly doesn’t want to load itsbilly.py by default. HOWEVER, if you sayimport xxx.yyy as zzz then it will put the module-object resulting from executingxxx/yyy.py as the variablezzz in the current namespace!!!!! This is the way it is because it serves all the normal use-cases in a compact syntax but I go insane every time I try to explain it. Truly a victory for the semantic compressor at the expense of everyone else.

Conclusion

The survivability onion meme, but the layers are relabeled to say: don't use a computer, don't write code, don't write python, don't write bad python, don't get mad about bad python, don't write blog posts about bad python
The survivability onion meme, but the layers are relabeled to say: don’t use a computer, don’t write code, don’t write python, don’t write bad python, don’t get mad about bad python, don’t write blog posts about bad python
Audrey DutcherA beginner's guide to NixOS channels vs flakes2025-10-06 00:00-0700An overview of how to manage your NixOS system configuration, specifically how to manage which version of nixpkgs you're using

The goal here is to answer the question “how does your system know what version of nixpkgs to use”, i.e. “how do you tell what version of firefox I am going to get when I ask for firefox to be installed”.

There are two approaches, channels and flakes. The long and the short of this is that channels are a mechanism baked into your system1 and flakes are a mechanism stored in a file next to your configuration.

I do not know of a version of managing either of these that doesn’t involve using the terminal the entire time.

Channels

To manage channels, you will use thenix-channel command in the terminal. You will need to run it as the root (administrator) user, i.e. prefix the command withsudo. This can be confusing because if you runnix-channel as your non-privileged user, i.e. the default when you don’t prefix withsudo, it will still do something, but that something will almost certainly not be what you want!

Start withsudo nix-channel --list. This will list all the channels that are being managed by your system. Usually there is just one, named “nixos”. You can see that it probably points at something like https://nixos.org/channels/nixos-25.05.

If NixOS 25.11 were to come out tomorrow, you would just change the 25.05 to 25.11 and you would get all the shiny new software. You can do this withsudo nix-channel --add https://nixos.org/channels/nixos-25.11 nixos.

If you simply want to do a light upgrade and get only the software vetted for the 25.05 release but with any important fixes that have been discovered since release, you just wantsudo nix-channel --update nixos. This will check if there is a new version of 25.05 available and switch to it if there is. Weird that even though there’s a version number, there’s subversions of that version…

Flakes

Flakes are the alternative which doesn’t bake anything into your system, and are in fact philosophically designed to avoid having to bake anything into your system. The “goal” per se is to make it so that you can share a folder of files and suddenly your system is fully 100% reproducable, locking in place the version of nixpkgs (and potentially more things!) in a way that is simply just in a text file and is easily sharable.

These text files are named flake.nix and flake.lock. flake.nix is a file that you can edit, technically in the same language as your configuration.nix file but using some more arcane features. flake.lock is still a text file but you are not meant to edit it by hand. Instead, you run thenix flake update command, and the flake.lock file is automatically regenerated with the newest version of everything.

Writing a flake.nix file is a little weird, you would probably just want to copy one from someone else online. Maybe start with2 I don’t think I can explain how to write one from first principles in just this document. However, once you find one, it will also contain a line which basically says “nixpkgs is going to be a version named 25.05”. If you edit this file to say 25.11, your next system build will use 25.11.

One of the other benefits of using flakes is that you can put your configuration.nix and hardware-configuration.nix files anywhere, not just in /etc/nixos. You will have to put them in the same folder of flake.nix and flake.lock (or in a folder next to those files), but you can put the folder containing all that crap literally wherever.

One final caveat is that if you have a git repository that contains your flake files, nix will ignore files which are in that folder but not tracked by git. This doesn’t matter unless you start using git on the command line :)

A table comparing terminal commands

Goal Channels solution Flakes solution
Switch to the most recent release of your current version of nixossudo nix-channel --update nixosnix flake update (Automatically edits flake.lock)
Switch to a different release version of nixossudo nix-channel add ... nixos Edit flake.nix
Build a configuration and make your system use itsudo nixos-rebuild switch3sudo nixos-rebuild switch --flake path/to/folder-that-has-flake-stuff

The dirty details

The nix programming language has a weird escape hatch for accessing external resources at evaluation time. If you ever see nix code that looks likewith import <nixpkgs> {}; blah blah, this is using this escape hatch! This syntax, the import with angle brackets, refers to an “impure” resource, i.e, some sort of external truth which dictates what code you actually mean by nixpkgs. This is widely considered to be a bit of a wart on the language’s beautiful face! People love nix for its purity (technical term) and its reproducability, and this capability shoots that down immediately. Flakes are designed to be the solution to this - the angle brackets import syntax simply will not work in the “pure” evaluation mode, which is used when working with flakes. Instead, the nix interpreter understands the special structure of the flake.nix and flake.lock files and reads these in order to populate a list of inputs, which it provides to code running in the flake.nix file (outputs). In this guide, nixpkgs has been the only input, but you can use lots of other things as inputs! Random github repositories that have a flake.nix if you like!

The flake.nix structure is actually a very extensible structure that can be used for lots of things other than a NixOS system configuration. Take a look at4 for all the things that can be done :)

  1. Associated with the root account, in /nix/var/nix/profiles/per-user/root/channels ↩︎

  2. https://wiki.nixos.org/wiki/NixOS_system_configuration#Defining_NixOS_as_a_flake ↩︎

  3. This will by default use /etc/nix/configuration.nix ↩︎

  4. https://wiki.nixos.org/wiki/Flakes ↩︎

Audrey DutcherHello Blog - How I streamlined my application management with Nix2025-04-20 00:00-0700The obligatory blog boot-up post about how I built the blog

As you know if you’re part of my life, I have been going pretty hard on nixing my workstations and servers lately. This post is to commemorate the creation of this blog being run through nix, but also the workflow I’ve established to get here.

Since the year is 2025 and attention span is in short supply, here’s the punchline:

  • I rannix run .#sunflower.deploy to update my server, including deploying this blog
  • I will runnix run .#sunflower.deploy.blog-rhelmot-io to update the blog without updating the system profile
  • …but I can still roll the blog forward and back without rolling the system forward and back, because the blog is its own nix profile!

Let’s break it down.

Part 1: Static Site Generation

What a hotly contentious topic. I could probably stand to care a little bit less, but the caring I do care isn’t much. I started this journey trying to use Jekyll, but quickly found that the Ruby-isms were too much for me. I did at one point succeed at gettinga flake output which could build a whole Jekyll site, but it was too much of a hack for me to deign to put it upon my domain.

I eventually foundCoricamu, which is exactly what I want, though it seems to be abandoned. It’s small enough that I feel comfortable carrying it on my shoulders, so I forked it and did the one small fix necessary to get it to work with current nixpkgs. I may mess around with theming later, but it provides exactly what I want and not much more.

The source for this blog can be foundhere.

Coricamu lets you build a site through a NixOS-style module system. I constructed my flake.nix such that it runs module evaluation with two modules:

  • theblog.nix file, defining the site metadata
  • a module constructed automatically by slapping each entry of/posts/*/post.nix into a post directive
let
posts = let
listingMap = builtins.readDir ./posts;
listing = builtins.attrNames listingMap;
getPostFile = post: (import ./posts/${post}/post.nix) // { slug = post; };
in builtins.map getPostFile listing;
in
coricamu.lib.generateFlakeOutputs {
outputName = "blog";
modules = [ ./blog.nix { inherit posts; }];
};

Then I just write some posts in markdown, put some quick metadata into a .nix file which references the markdown file, and build:nix build .#blog. I can alsonix run .#blog-preview if I want a fancy server. Truly, we stand on the shoulders of giants.

Part 2: Managing Multiple Machines

I have several machines I manage with acentral NixOS configuration repository - some workstations and some servers. This flake.nix also does a directory scan in order to populate its outputs, this time scanningsites in order to populatepackages.${buildSystem}.nixosConfigurations.${site}.

Yes,nixos-rebuild will automatically searchpackages.${buildSystem} in order to build a system, allowing for cross compilation. This fact is particularly useful seeing as I work onNixBSD and am constantly cross compiling entire systems. There are various accoutrements in this repository which make it reasonable for me to use it for both NixOS and NixBSD systems, but that’s a story for another time.

Now, I can deploy any of these systems withnixos-rebuild .#$HOST --remote-target $HOST --use-remote-sudo switch, ideally with--use-substitutes since my home internet uplink is dogshit.

There is a problem though - if I want to have my blog as a nix derivation, this means that I have to run a full system rebuild every time I publish a new post. It is very easy to simply drop the derivation output into the nginx configuration, but suddenly rollbacks are tied together with both the system and blog. Can we do better?

Part 3: Profiles and Deployment

Yes, we can, with the power ofNix Profiles! We won’t be linking the typical kind of derivation output you would usually be putting in a user profile, with the system path and applications and such. Instead, our profile will simply be the static site build output derivation!

I may in the future decide to standardize some sort of “nginx site derivation” layout so I can link non-static sites this way, but for now I just point the root of the site at/nix/var/nix/profiles/blog-rhelmot-io, and deploy as follows:

nix-copy-closure --to $SITE $DRV
ssh $SITE sudo nix-env --set -p /nix/var/nix/profiles/blog-rhelmot-io $DRV

This can be automated! Checkdeploy.nix in my NixOS configuration for the final product. I define a list of deployments, each of which sets a profile name, a site to deploy on, and the package to deploy:

deployments = builtins.map mkDeploy [
{
profileName = "blog-rhelmot-io";
site = "sunflower";
targetPkg = flakeInputs."blog-rhelmot-io".packages.${platform}.blog;
}
];

mkDeploy simply templates the previously-mentioned script with these parameters. We can then combine each script for a given site into a unified deploy script, along with a system profile rebuild for good measure:

filteredDeployments = builtins.filter (deployment: deployment.site == site) deployments;
targetSystem = flakeInputs.self.packages.${platform}.${site}.system;
deployAll = pkgs.writeShellScriptBin "deploy-all-${site}" (''
set -ex
# TODO take advantage of the nixos-rebuild infrastructure
nix-copy-closure --to ${site} ${targetSystem}
ssh ${site} 'sudo nix-env --set -p /nix/var/nix/profiles/system ${targetSystem} && sudo ${targetSystem}/bin/switch-to-configuration switch'
set +e
'' + lib.concatStringsSep "\n" filteredDeployments);

It is annoying thatnixos-rebuild proper doesn’t support this use-case - that is, deploying a pre-built system profile. I have made the requisite change to enable this behavior in theNixBSD fork of nixos-rebuild, but this script is obviously only appropriate for building BSD targets.

Finally, we can deploy just the blog with a sub-attribute,nix run .#sunflower.deploy.blog-rhelmot-io:

filteredDeploymentsAttrs = builtins.listToAttrs (builtins.map (value: { name = value.profileName; inherit value; }) filteredDeployments);
final = deployAll // filteredDeploymentsAttrs;

I believe this is the best of both worlds.

Conclusion

Yippee woo hoo ya ha ha

You too can take control of your systems like this. Go forth and nixify!

Audrey Dutcher