docsv0.5.1

Environment variables

Every URNA_* environment variable urna reads, plus the other variables that change its behavior, with the component that reads each, its default and effect.

This page lists every URNA_* variable read anywhere in the urna code, grouped by who reads it, and then the other environment variables that change urna's behavior. Unless a row says otherwise, an empty value counts as unset.

Install and setup

VariableRead byDefaultEffect
URNA_RELEASE_BASEinstall.sh, install.ps1, urna setupthe GitHub release: the latest one for the installers (or --version), the binary's own version for setup (or --version)URL prefix the release files are fetched from, used as given (setup trims a trailing /). When set, the version flags of all three are ignored. urna setup accepts only https:// and file://; install.sh accepts any URL curl does. See air-gapped install.
URNA_BIN_DIRinstall.sh, install.ps1~/.local/bin (~\.local\bin on Windows)Where the installers put the binary. The binary itself never reads it.
URNA_DATA_DIRinstall.sh, install.ps1, urna setup, and every urna command that looks for the embedder, the build tool or the setup venvunsetThe first data directory searched, and the directory urna setup and the installers write into. The payload lands in $URNA_DATA_DIR/urna/forge, the venv in $URNA_DATA_DIR/urna/venv. Keep it set for every later urna run, or the binary looks only in the default locations. See paths.

The urna binary

VariableRead byDefaultEffect
URNA_PYTHONask, retrieve, search-text, build, doctor, the explorer, urna setupunsetThe interpreter that runs the query embedders and the build tool, used verbatim. It wins over the setup venv, any .venv and python3. When it points at an interpreter without numpy and tokenizers, urna setup blocks its Python step (exit 14) instead of building a venv this variable would hide.
URNA_COLORurna tui, urna setup, urna doctorunset (the terminal is probed)none: no color. 256: the xterm 256-color palette. truecolor or 24bit: 24-bit color. Any other value falls through to the probe. NO_COLOR wins over it. See colors and links.
URNA_FORCE_SCALARthe runtime (every search, in the binary and in the Python extension)unsetAny value except 0, including an empty one, disables SIMD and uses the scalar code path. urna doctor and urna stats then report scalar. For before and after benchmarks on one binary.

Python embedders and the build (repo checkout)

These are read by the Python side, which runs from a repo checkout: the forge behind urna build, the registry query embedder, and search-text's embedder. The installed payload's potion embedder reads none of them.

VariableRead byDefaultEffect
URNA_ALLOW_DOWNLOADpython/embed_query.py (search-text), python/model_fingerprint.py, python/convert_legacy.py, python/tools/urna_build_corpus.py, python/forge/embed_st.pyunsetExactly 1 allows Hugging Face downloads of model weights. Any other value keeps HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE and HF_DATASETS_OFFLINE at 1 (unless you set them yourself).
URNA_ALLOW_REMOTE_CODEpython/forge/embed_query_model.py (ask and retrieve on registry-model corpora), python/tools/urna_model_bench.py, python/tools/urna_ui_bridge.pyunsetComma-separated preset names allowed to run the model's remote code (trust_remote_code), for example wemm-2b,jina-v5-omni-nano. A query against such a preset without it fails. At build time the spec's [output] allow_remote_code plays this role.
URNA_ALLOW_HEAVYpython/forge/embed_query_model.pyunsetExactly 1 lets the query embedder load a preset flagged too heavy for this machine (wemm-4b, wemm-9b). At build time, use urna build --allow-heavy.
URNA_CACHE_DIRthe forge (urna build)${XDG_CACHE_HOME:-~/.cache}/urnaRoot of the shared embed cache and model probes. [output] cache_dir in the spec and --cache-dir take precedence. ~ is expanded.
URNA_MODEL_DIR_<NAME>the model registry (build and registry query embedder)unsetLocal directory of a preset's model. <NAME> is the preset name upper-cased with - as _: URNA_MODEL_DIR_WEMM_2B. An explicit model path (model_path in the spec, --model-path on ask and retrieve) wins over it; it wins over the preset's own local directory and the Hugging Face cache.
URNA_ST_DEVICEthe forge's sentence-transformers workerscuda if available, else mps, else cpuDevice for embedding. Recorded as device in the build lock (auto when unset).
URNA_ST_DTYPEthe forge's sentence-transformers workersbfloat16 on cuda, float16 on mps, float32 on cpuModel dtype for embedding.
URNA_ENABLE_FAKE_PRESETthe model registryunsetExactly 1 enables the fake-test preset, used by the test suite.

The model presets and their requirements are in the model registry; the cache layout is in build artifacts.

Examples

VariableRead byDefaultEffect
URNA_FILEexamples/fastapi/main.py, examples/flask/app.pydemo_fastapi.urna, demo_flask.urnaThe corpus the demo server opens; a demo corpus is built there when the file does not exist.

Development and tests

VariableRead byDefaultEffect
URNA_PYTHONscripts/release_check.sh, scripts/ruff_check.shrelease_check.sh: ./.venv/bin/python if present, else python3; ruff_check.sh: python3The interpreter the gate builds the extension against and runs the Python suites and ruff with.
URNA_BASELINEscripts/release_check.shdata/measure/baseline.jsonBaseline JSON the measurement is compared against.
URNA_QUERIESscripts/release_check.sh100Query count for measure_presets.py.
URNA_Kscripts/release_check.sh10Top-k for measure_presets.py.
URNA_OUTscripts/release_check.sh/tmp/release_check_post.jsonWhere the post-run measurement JSON is written.
URNA_MUTATION_ITERScrates/urna-format/tests/mutation_fuzz.rs, crates/urna-runtime/tests/mutation_fuzz.rs1500 (format), 250 (runtime)Iterations per fixture of the mutation harness. CI sets 6000 and 800.
URNA_FUZZ_SEED_DIRthe same two harnessesunsetOutput directory: the harness writes its base fixtures there, to seed the cargo-fuzz corpus.
URNA_FUZZ_TARGETSscripts/fuzz_soak.shurna-view section-decoders runtime-indexes mmap-open-searchSpace-separated cargo-fuzz targets for a local soak.
URNA_FORGE_TEST_DATAtests/test_forge_spec.pyset by the testFixture for the spec's ${VAR} expansion.
URNA_FORGE_UNSET_Xtests/test_forge_spec.pykept unsetChecks the error for an unset ${VAR}.

The contributor workflow is in contributing.

Other variables urna reads

VariableRead byEffect
NO_COLORurna tui, urna setup, urna doctorA non-empty value disables color. An empty NO_COLOR is ignored.
COLORTERM, TERM_PROGRAM, TERMthe color probePick 24-bit color when they name a truecolor terminal; the list is in colors and links.
WT_SESSIONthe color probe, the explorer's linksSet by Windows Terminal: selects 24-bit color and enables OSC 8 links on Windows.
XDG_DATA_HOMEthe binary, install.shSecond data directory searched; the install root when URNA_DATA_DIR is unset (after LOCALAPPDATA on Windows).
HOMEthe binary, install.sh, install.ps1$HOME/.local/share is a data directory; ~ in displayed paths.
LOCALAPPDATAthe binary, install.ps1A data directory on every OS; the install root on Windows when URNA_DATA_DIR is unset.
PATH, PATHEXTurna setupFinding curl, uv and a base Python (PATHEXT suffixes on Windows).
XDG_CACHE_HOMEthe forgeDefault parent of the embed cache: $XDG_CACHE_HOME/urna.
HF_HOMEpython/model_fingerprint.pyWhere the Hugging Face cache is looked up (default ~/.cache/huggingface).
HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE, HF_DATASETS_OFFLINEset by the potion embedder and the sentence-transformers scriptsSet to 1 when you have not set them, so Hugging Face libraries stay offline.
TOKENIZERS_PARALLELISMset by the potion embedderSet to false when you have not set it.
any ${VAR} in a build specthe forgeExpanded in spec strings; unset or empty is a spec error. See the spec file.
PYO3_PYTHONset by scripts/release_check.shPins the interpreter the extension is built against.
HTTPS_PROXY, HTTP_PROXY, NO_PROXYthe npm wrapper of @urna/cliProxy for its download. curl, which the installers and urna setup use, reads its own proxy variables.

Names such as URNA_MAGIC, URNA_HEADER_SIZE, URNA_FORMAT_VERSION or URNA_BIN that appear in the code are constants, not environment variables.

Compatibility

Which .urna files a 0.5.1 reader accepts, how format v1 grows without breaking old files, legacy NEST files and what makes two builds byte-identical.

Paths and resolution order

Where urna keeps the embedder payload, the setup venv and the embed cache, and the exact order it searches for data directories, scripts and Python.

On this page

Install and setupThe urna binaryPython embedders and the build (repo checkout)ExamplesDevelopment and testsOther variables urna reads