Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
name: ci

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
nix:
name: nix build + run
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: DeterminateSystems/determinate-nix-action@v3
- name: Evaluate flake outputs
run: nix flake show
- name: Build the closed world
run: nix build --print-build-logs
- name: Run the product (network-free)
run: nix run .#
- name: Import inside the declared env
run: |
nix develop --command python -c \
"import python_gate, rich; print(python_gate.greet())"

uv:
name: uv sync --locked
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: astral-sh/setup-uv@v6
- name: Sync from uv.lock (packages, not a closure)
run: uv sync --locked
- name: Run via the uv-managed env
run: uv run python-gate
10 changes: 10 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.venv/
result
result-*
__pycache__/
*.py[cod]
*.egg-info/
.direnv/
dist/
build/
.python-version
119 changes: 118 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,119 @@
# python-gate
Nix as Python's missing gate: uv owns the expression, Nix closes the world, nix run is the product.

**This is a GitHub template.** Use it as *Use this template*, or:

```bash
nix flake new -t github:Hedronite/python-gate ./my-app
```

Nix is the gate. uv owns the expression. `nix run` is the product.

`mkVirtualEnv` / `withPackages` builds a world; `mkApplication` / `wrapProgram` locks the door; nix-ld is the FHS lie (unsafe, Level 2).

A Python shop that is not on NixOS still `uv sync`s from `uv.lock`. A Nix user or CI `nix develop`s and `nix run .#`s the same closure. Two proofs: `uv.lock` (packages) and `flake.lock` (builders). **A lockfile is not a closure.**

This repository is the working example *and* the cloneable template. v1 is Level 3: no CUDA, no PyO3, no native extensions.

## The ladder

| Level | What you have | What you do not have |
| --- | --- | --- |
| 0 | Host Python, `pip install` | A lock, a world, a product |
| 1 | `uv.lock` / `poetry.lock` | A closure. Builders are the host |
| 2 | nix-ld / steam-run / `LD_LIBRARY_PATH` | Bit-identity. This is the FHS lie |
| **3** | **uv2nix `mkVirtualEnv` + `mkApplication`. This template** | CUDA, PyO3, native extensions |
| 4 | Native/FFI bits patched into the store | (out of scope for v1) |

Level 2 can run a wheel. It is not a closed world. Do not claim it is bit-identical.

## Init

```bash
# GitHub template, or:
nix flake new -t github:Hedronite/python-gate ./my-app
cd ./my-app

# Rename the project: pyproject.toml [project] name, [project.scripts],
# src/<module>/, and `projectName` in flake.nix. Then:
uv lock
```

Without Nix (inner loop):

```bash
uv sync
uv run python-gate
```

With Nix (same world, locked door):

```bash
nix develop # store venv + peace treaty
nix run .# # the product; network-free
```

## Add a dependency

uv writes the expression. Nix consumes it. Do not hand-translate `uv.lock` into `python3Packages`.

```bash
uv add httpx # or any pure-Python wheel uv2nix can eat
git add uv.lock pyproject.toml
nix run .# # rebuilds the world from the new lock
git add flake.lock # only if flake inputs moved
git commit
```

Commit **both** lockfiles. `uv.lock` pins packages. `flake.lock` pins builders. Either one alone is a story, not a closure.

## Peace treaty (dev shell)

The Nix shell and uv share one interpreter. They do not share authority over the environment.

| Variable | Value | Why |
| --- | --- | --- |
| `UV_NO_SYNC` | `1` | uv must not provision a second venv |
| `UV_PYTHON` | the Nix interpreter | one Python set |
| `UV_PYTHON_DOWNLOADS` | `never` | Nix owns the interpreter |
| `PYTHONPATH` | unset in `shellHook` | kill nixpkgs `PYTHONPATH` leakage |

On NixOS, if you must run an **unpatched** FHS binary, set `NIX_LD` and `NIX_LD_LIBRARY_PATH` (nix-ld). **Never set `LD_LIBRARY_PATH` as the default.** That is a Level 2 leak into a Level 3 world.

## Must not

- Keep a second venv (`.venv`) beside the store venv. `uv run` inside `nix develop` is how you grow a second world.
- Use poetry2nix. It is unmaintained. This template is uv + uv2nix.
- Claim Level 2 (nix-ld / `LD_LIBRARY_PATH`) is bit-identical.
- Edit `uv.lock` or `flake.lock` by hand.
- Hand-translate `uv.lock` into `python3Packages`.
- Set `LD_LIBRARY_PATH` as the default on NixOS.

## Agent grading

A change is done when all of these pass:

1. **Flake eval.** `nix flake show` lists `packages.<system>.default`, `devShells.<system>.default`, and `templates.default`. Systems: `x86_64-linux`, `aarch64-linux`, `aarch64-darwin` (nixos-unstable dropped Intel Macs).
2. **Import inside the declared env.** `nix develop --command python -c "import python_gate, rich"` succeeds.
3. **`uv sync --locked`.** The non-Nix inner loop still reproduces from `uv.lock`.
4. **Same closure.** `nix run .#` and `nix develop` use the same Python set (same interpreter, same uv2nix overlay). The product is the wrapped application, not a hope.

CI on `ubuntu-latest` runs `nix build` / `nix run` (Determinate Nix) and `uv sync --locked` (setup-uv). Green means both proofs held, not that one was skipped.

## Example app

`src/python_gate` is a console script plus `rich`. `nix run .#` prints versions and `square(12)` — a pure function, no HTTP. That is the point: the closure is enough.

## Further reading

Short doctrine: [`docs/theses.md`](docs/theses.md).

Upstream builders (2026 map — do not use last year's):

- [uv](https://docs.astral.sh/uv/)
- [uv2nix](https://pyproject-nix.github.io/uv2nix/)
- [pyproject.nix](https://pyproject-nix.github.io/pyproject.nix/)
- [pyproject-build-systems](https://github.com/pyproject-nix/build-system-pkgs)

## License

MIT. Copyright Hedronite 2026.
25 changes: 25 additions & 0 deletions docs/theses.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Twelve theses

1. **The Python environment is part of the program.** An interpreter, a set of wheels, and a script are one artifact. Shipping the script alone is a wish.

2. **A lockfile is not a closure.** `uv.lock` pins packages. `flake.lock` pins builders. The closure is the store paths those two proofs evaluate to.

3. **uv owns the expression.** Add, remove, and pin through `pyproject.toml` / `uv.lock`. Do not hand-translate the lock into `python3Packages`. Do not edit lockfiles by hand.

4. **Nix is the gate.** Nothing enters the world except through evaluation. If it does not evaluate, it is not a dependency.

5. **`mkVirtualEnv` / `withPackages` builds a world.** Individual packages are not a product. The aggregated environment is.

6. **`mkApplication` / `wrapProgram` locks the door.** The virtualenv is an implementation detail. The product is a wrapped binary.

7. **Wrapping is FFI.** The ABI of the program is the store path, not `LD_LIBRARY_PATH`, not the host `libstdc++`, not a hope that the wheel matches the machine.

8. **Eval is the critic.** Tests that run against a second venv are reviewing a different play. `nix flake show`, import inside the declared env, `nix run`.

9. **The product is `nix run`.** A green `uv sync` is a proof of packages. The product is the closed world a stranger can run without becoming you.

10. **nix-ld is the FHS lie.** It is Level 2: useful for unpatched binaries, unsafe as a default, and never bit-identical. On NixOS use `NIX_LD` / `NIX_LD_LIBRARY_PATH`. Never set `LD_LIBRARY_PATH` as the default.

11. **One Python set.** `devShells.default` and `packages.default` share the same interpreter and the same uv2nix overlay. Editables on the shell are a lens, not a second world. The peace treaty (`UV_NO_SYNC`, `UV_PYTHON`, `UV_PYTHON_DOWNLOADS=never`, unset `PYTHONPATH`) is how they stay one.

12. **This template is Level 3.** No CUDA, no PyO3, no native extension in v1. Level 4 is a different door. Do not pretend Level 2 is this one.
99 changes: 99 additions & 0 deletions flake.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading