NOX(1)

📦
version 2025.11.12 · 3 versions
, in ubuntu stonking

👑 NOX(1) — User Commands, but make it a group chat 👑

bestie. sit down. hydrate. this is the manual page for nox, filed under User Commands in your friendly neighbourhood man section 1, and I am so normal about it. it's giving "python automation that actually respects you". let's get into it 💅

✨ NAME ✨

nox — Flexible test automation

🌸 DESCRIPTION 🌸

here's the vibe, straight up:

usage: nox [-h] [--version] [--script-mode {none,fresh,reuse}]
       [--script-venv-backend SCRIPT_VENV_BACKEND] [-l] [--json] [-s
       [SESSIONS ...]] [-p [PYTHONS ...]] [-k KEYWORDS] [-t [TAGS ...]]
       [-v] [--no-verbose] [-ts] [-db
       {conda,mamba,micromamba,virtualenv,venv,uv,none}] [-fb
       {conda,mamba,micromamba,virtualenv,venv,uv,none}] [--no-venv]
       [--reuse-venv {yes,no,always,never}] [-r] [-N] [-R] [-f NOXFILE]
       [--envdir ENVDIR] [--download-python {auto,never,always}]
       [--extra-pythons [EXTRA_PYTHONS ...]] [-P [FORCE_PYTHONS ...]]
       [-x] [--no-stop-on-first-error] [--error-on-missing-interpreters]
       [--no-error-on-missing-interpreters] [--error-on-external-run]
       [--no-error-on-external-run] [--install-only] [--no-install]
       [--report REPORT] [--non-interactive] [--nocolor] [--forcecolor]
       ...

and the one-sentence summary, no notes:

Nox is a Python automation toolkit.

that's it. that's the whole thesis. but the options?? the options are deep. buckle up 🫶

🎀 General options: 🎀

these are the general arguments used when invoking Nox, bestie. the little welcome committee.

  • -h, --help — Show this help message and exit. the classic. the escape hatch. iconic.
  • --version — Show the Nox version and exit. she tells you who she is and then leaves. main character energy.
  • --script-mode {none,fresh,reuse} — okay so real talk, the original page gives zero description for this one. not one word. she's mysterious 💀 I'm not gonna invent behaviour for her (the rules are the rules), so just know the flag is exactly --script-mode {none,fresh,reuse} and the manpage leaves it at that.
  • --script-venv-backend SCRIPT_VENV_BACKEND — same situation, babes. no description in the source text. the argument is literally SCRIPT_VENV_BACKEND and I refuse to make things up about it. respect the lore.
  • posargs — Arguments following -- that are passed through to the session(s). yep — everything after the double dash gets yeeted straight to your sessions ✨
  • -f, --noxfile NOXFILE — Location of the Python file containing Nox sessions. tell her where your sessions live 🏠

💖 Sessions options: 💖

these arguments are used to control which Nox session(s) to execute. picking your fighters.

  • -l, --list-sessions, --list — List all available sessions and exit. window shopping, but for sessions 🛍️
  • --json — JSON output formatting. Requires list-sessions currently. yes bestie, currently it's a package deal.
  • -s, -e, --sessions, --session [SESSIONS ...] — Which sessions to run. By default, all sessions will run. so if you say nothing, everything happens. the audacity.
  • -k, --keywords KEYWORDS — Only run sessions that match the given expression. filter by vibe. er, by expression.
  • -t, --tags [TAGS ...] — Only run sessions with the given tags. tag-based selection, slay.

🦋 Python options: 🦋

these arguments are used to control which Python version(s) to use. the interpreter guest list.

  • -p, --pythons, --python [PYTHONS ...] — Only run sessions that use the given python interpreter versions. pick your pythons carefully, queen.
  • --download-python, --download-python {auto,never,always} — When should nox download python standalone builds to run the sessions, defaults to 'auto' which will download when the version requested can't be found in the running environment. so auto = "if I can't find her here, I'll go get her" 🧚
  • --extra-pythons, --extra-python [EXTRA_PYTHONS ...] — Additionally, run sessions using the given python interpreter versions. not instead of — additionally. she's inclusive like that.
  • -P, --force-pythons, --force-python [FORCE_PYTHONS ...] — Run sessions with the given interpreters instead of those listed in the Noxfile. This is a shorthand for --python=X.Y --extra-python=X.Y. It will also work on sessions that don't have any interpreter parametrized. so it overrides the Noxfile and it still shows up for the sessions with no interpreter parametrized at all. no session left behind 💅

🌈 Environment options: 🌈

these arguments are used to control Nox's creation and usage of virtual environments. the whole venv cinematic universe.

  • -db, --default-venv-backend {conda,mamba,micromamba,virtualenv,venv,uv,none} — Virtual environment backend to use by default for Nox sessions, this is 'virtualenv' by default but any of ['conda', 'mamba', 'micromamba', 'virtualenv', 'venv', 'uv', 'none'] are accepted.
  • -fb, --force-venv-backend {conda,mamba,micromamba,virtualenv,venv,uv,none} — Virtual environment backend to force-use for all Nox sessions in this run, overriding any other venv backend declared in the Noxfile and ignoring the default backend. Any of ['conda', 'mamba', 'micromamba', 'virtualenv', 'venv', 'uv', 'none'] are accepted. it overrides everything — "ignoring the default backend" is not a drill, she means it.
  • --no-venv — Runs the selected sessions directly on the current interpreter, without creating a venv. This is an alias for '--force-venv-backend none'.
  • --reuse-venv {yes,no,always,never} — Controls existing virtualenvs recreation. This is 'no' by default, but any of ('yes', 'no', 'always', 'never') are accepted.
  • -r, --reuse-existing-virtualenvs — This is an alias for '--reuse-venv=yes|no'.
  • -N, --no-reuse-existing-virtualenvs — Disables --reuse-existing-virtualenvs if it is enabled in the Noxfile. the paranoia flag. valid.
  • -R — Reuse existing virtualenvs and skip package reinstallation. This is an alias for '--reuse-existingvirtualenvs --no-install'. fastest princess in the kingdom 🔥
  • --envdir ENVDIR — Directory where Nox will store virtualenvs, this is .nox by default. that little .nox folder? hers.

🔥 Execution options: 🔥

these arguments are used to control execution of sessions. the part where things actually run.

  • -x, --stop-on-first-error — Stop after the first error.
  • --no-stop-on-first-error — Disables --stop-on-first-error if it is enabled in the Noxfile.
  • --error-on-missing-interpreters — Error instead of skipping sessions if an interpreter can not be located. so if she can't find the interpreter, she doesn't ghost the session — she errors.
  • --no-error-on-missing-interpreters — Disables --error-on-missing-interpreters if it is enabled in the Noxfile.
  • --error-on-external-run — Error if run() is used to execute a program that isn't installed in a session's virtualenv.
  • --no-error-on-external-run — Disables --error-on-external-run if it is enabled in the Noxfile.
  • --install-only — Skip session.run invocations in the Noxfile. install era, no running era.
  • --no-install — Skip invocations of session methods for installing packages (session.install, session.conda_install, session.run_install) when a virtualenv is being reused.
  • --non-interactive — Force session.interactive to always be False, even in interactive sessions. she said no talking.

⭐ Reporting options: ⭐

these arguments are used to control Nox's reporting during execution. the "tell me everything" corner.

  • -v, --verbose — Logs the output of all commands run including commands marked silent. yes, including the shy ones.
  • --no-verbose — Disables --verbose if it is enabled in the Noxfile.
  • -ts, --add-timestamp — Adds a timestamp to logged output. for the girlies who need receipts ⏰
  • --report REPORT — Output a report of all sessions to the given filename.
  • --nocolor, --no-color — Disable all color output. 😭
  • --forcecolor, --force-color — Force color output, even if stdout is not an interactive terminal. the opposite of the above and honestly? respect.

📚 SEE ALSO 📚

The full documentation for nox is maintained as a Texinfo manual. If the info and nox programs are properly installed at your site, the command

info nox

should give you access to the complete manual. go read it, bestie, she's smarter than my summary 🫶

and that's the whole page, fr fr. nothing dropped, nothing skipped, no flags invented.

this has been the nox page from nox 2025.11.12, dated July 2026, and that's the sign-off — slay, hydrate, and remember: flexible test automation periodt 💖✨

📦 where this page comes from