命令行用法

调用

Nox 通常是在命令行上调用的：

nox

你也可以通过 Python 解释器调用 Nox：

python3 -m nox

列出可用的会话

列出所有可用的会话，包括参数化的会话：

nox -l
nox --list
nox --list-sessions

运行所有会话

你可以通过执行 nox 来运行每个会话，不需要任何参数：

nox

会话的执行顺序是它们在 Noxfile 中出现的顺序。

指定一个或多个会话

默认情况下，Nox 将运行 noxfile 中定义的所有会话。然而，你可以选择使用 --session、-s 或 -e 来运行它们中的某一组：

nox --session tests
nox -s lint tests
nox -e lint

你也可以使用 NOXSESSION 环境变量。

NOXSESSION=lint nox
NOXSESSION=lint,tests nox

Nox 将按照指定的顺序运行这些会话。

如果你有 配置的会话的 virtualenv，你可以选择只运行具有指定 Python 版本的会话：

nox --python 3.8
nox -p 3.7 3.8

你也可以使用 pytest-style keywords 来过滤测试会话。

nox -k "not lint"
nox -k "tests and not lint"

指定参数化的会话

如果你有 参数化 会话，如：

@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    ...

然后运行 nox --session tests 实际上将运行所有参数化的会话版本。如果你想用一组特定的参数来运行会话，你可以用会话名称来指定它们：

nox --session "tests(django='1.9')"
nox --session "tests(django='2.0')"

改变会话的默认后端

默认情况下，nox 使用 virtualenv 作为会话的虚拟环境后端，但它也支持 conda、mamba 和 venv 以及无后端（直通到 nox 运行的任何 python 环境）。你可以通过使用 -db <backend> 或 --default-venv-backend <backend> 来改变默认行为。支持的名称是 ('none', 'virtualenv', 'conda', 'mamba', 'venv')。

nox -db conda
nox --default-venv-backend conda

你也可以在 Noxfile 中用 nox.options.default_venv_backend 设置这个选项。如果两者都提供，则以命令行参数为准。

注意，使用这个选项不会改变明确设置了 venv_backend 的会话的后端。

强制使用会话后端

You might work in a different environment than a project’s default continuous integration settings, and might wish to get a quick way to execute the same tasks but on a different venv backend. For this purpose, you can temporarily force the backend used by all sessions in the current nox execution by using -fb <backend> or --force-venv-backend <backend>. No exceptions are made, the backend will be forced for all sessions run whatever the other options values and nox file configuration. Supported names are ('none', 'virtualenv', 'conda', 'venv').

nox -fb conda
nox --force-venv-backend conda

You can also set this option in the Noxfile with nox.options.force_venv_backend. In case both are provided, the commandline argument takes precedence.

Finally note that the --no-venv flag is a shortcut for --force-venv-backend none and allows to temporarily run all selected sessions on the current python interpreter (the one running nox).

nox --no-venv

Re-using virtualenvs

By default, Nox deletes and recreates virtualenvs every time it is run. This is usually fine for most projects and continuous integration environments as pip’s caching makes re-install rather quick. However, there are some situations where it is advantageous to re-use the virtualenvs between runs. Use -r or --reuse-existing-virtualenvs:

nox -r
nox --reuse-existing-virtualenvs

If the Noxfile sets nox.options.reuse_existing_virtualenvs, you can override the Noxfile setting from the command line by using --no-reuse-existing-virtualenvs.

Additionally, you can skip the re-installation of packages when a virtualenv is reused. Use -R or --reuse-existing-virtualenvs --no-install:

nox -R
nox --reuse-existing-virtualenvs --no-install

The --no-install option causes the following session methods to return early:

• session.install

• session.conda_install

• session.run_always

This option has no effect if the virtualenv is not being reused.

Running additional Python versions

In addition to Nox supporting executing single sessions, it also supports running Python versions that aren’t specified using --extra-pythons.

nox --extra-pythons 3.8 3.9

This will, in addition to specified Python versions in the Noxfile, also create sessions for the specified versions.

This option can be combined with --python to replace, instead of appending, the Python interpreter for a given session:

nox --python 3.10 --extra-python 3.10 -s lint

Instead of passing both options, you can use the --force-python shorthand:

nox --force-python 3.10 -s lint

Also, you can specify python in place of a specific version. This will run the session using the python specified for the current PATH:

nox --force-python python -s lint

Stopping if any session fails

By default nox will continue to run all sessions even if one fails. You can use --stop-on-first-error to make nox abort as soon as the first session fails:

nox --stop-on-first-error

If the Noxfile sets nox.options.stop_on_first_error, you can override the Noxfile setting from the command line by using --no-stop-on-first-error.

Failing sessions when the interpreter is missing

By default, Nox will skip sessions where the Python interpreter can’t be found. If you want Nox to mark these sessions as failed, you can use --error-on-missing-interpreters:

nox --error-on-missing-interpreters

If the Noxfile sets nox.options.error_on_missing_interpreters, you can override the Noxfile setting from the command line by using --no-error-on-missing-interpreters.

Disallowing external programs

By default Nox will warn but ultimately allow you to run programs not installed in the session’s virtualenv. You can use --error-on-external-run to make Nox fail the session if it uses any external program without explicitly passing external=True into session.run:

nox --error-on-external-run

If the Noxfile sets nox.options.error_on_external_run, you can override the Noxfile setting from the command line by using --no-error-on-external-run.

Specifying a different configuration file

If for some reason your noxfile is not named noxfile.py, you can use --noxfile or -f:

nox --noxfile something.py
nox -f something.py

Storing virtualenvs in a different directory

By default nox stores virtualenvs in ./.nox, however, you can change this using --envdir:

nox --envdir /tmp/envs

Skipping everything but install commands

There are a couple of cases where it makes sense to have Nox only run install commands, such as preparing an environment for offline testing or re-creating the same virtualenvs used for testing. You can use --install-only to skip run commands.

For example, given this Noxfile:

@nox.session
def tests(session):
    session.install("pytest")
    session.install(".")
    session.run("pytest")

Running:

nox --install-only

Would run both install commands, but skip the run command:

nox > Running session tests
nox > Creating virtualenv using python3.7 in ./.nox/tests
nox > python -m pip install pytest
nox > python -m pip install .
nox > Skipping pytest run, as --install-only is set.
nox > Session tests was successful.

Forcing non-interactive behavior

session.interactive can be used to tell if Nox is being run from an interactive terminal (such as an actual human running it on their computer) vs run in a non-interactive terminal (such as a continuous integration system).

@nox.session
def docs(session):
    ...

    if session.interactive:
        nox.run("sphinx-autobuild", ...)
    else:
        nox.run("sphinx-build", ...)

Sometimes it’s useful to force Nox to see the session as non-interactive. You can use the --non-interactive argument to do this:

nox --non-interactive

This will cause session.interactive to always return False.

Controlling color output

By default, Nox will output colorful logs if you’re using in an interactive terminal. However, if you are redirecting stderr to a file or otherwise not using an interactive terminal, or the environment variable NO_COLOR is set, nox will output in plaintext. If this is not set, and FORCE_COLOR is present, color will be forced.

You can manually control Nox’s output using the --nocolor and --forcecolor flags.

For example, this will always output colorful logs:

nox --forcecolor

However, this will never output colorful logs:

nox --nocolor

Controlling commands verbosity

By default, Nox will only show output of commands that fail, or, when the commands get passed silent=False. By passing --verbose to Nox, all output of all commands run is shown, regardless of the silent argument.

Outputting a machine-readable report

You can output a report in json format by specifying --report:

nox --report status.json

Converting from tox

Nox has experimental support for converting tox.ini files into noxfile.py files. This doesn’t support every feature of tox and is intended to just do most of the mechanical work of converting over- you’ll likely still need to make a few changes to the converted noxfile.py.

To use the converter, install nox with the tox_to_nox extra:

pip install --upgrade nox[tox_to_nox]

Then, just run tox-to-nox in the directory where your tox.ini resides:

tox-to-nox

This will create a noxfile.py based on the environments in your tox.ini. Some things to note:

• Generative environments work, but will be converted as individual environments. tox-to-nox isn’t quite smart enough to turn these into parametrized sessions, but it should be straightforward to manually pull out common configuration for parametrization.

• Due to the way tox parses its configuration, all substitutions are baked in when converting. This means you’ll need to replace the static strings in the noxfile.py with appropriate variables.

• Several non-common tox options aren’t implemented, but it’s possible to do so. Please file a feature request if you run into one you think will be useful.

Shell Completion

Add the appropriate command to your shell’s config file so that it is run on startup. You will likely have to restart or re-login for the autocompletion to start working.

bash

eval "$(register-python-argcomplete nox)"

zsh

# To activate completions for zsh you need to have
# bashcompinit enabled in zsh:
autoload -U bashcompinit
bashcompinit

# Afterwards you can enable completion for nox:
eval "$(register-python-argcomplete nox)"

tcsh

eval `register-python-argcomplete --shell tcsh nox`

fish

register-python-argcomplete --shell fish nox | .