Command-line usage

Nox is normally invoked on the command line:


Specifying a different configuration file

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

nox --noxfile
nox -f

Storing virtualenvs in a different directory

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

nox --envdir /tmp/.

Listing available sessions

To list all available sessions, including parametrized sessions:

nox -l
nox --list-sessions

Running all sessions

You can run every session by just executing nox without any arguments:


The order that sessions are executed is the order that they appear in the Noxfile.

Specifying one or more sessions

By default nox will run all sessions defined in the noxfile. However, you can choose to run a particular set of them using --session, -s, or -e:

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

Nox will run these sessions in the same order they are specified.

You can also use pytest-style keywords to filter test sessions:

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

Specifying parametrized sessions

If you have a parametrized session such as:

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

Then running nox --session tests will actually run all parametrized versions of the session. If you want the run the session with a particular set of parametrized arguments, you can specify them with the session name:

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

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

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

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, nox will output in plaintext.

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


Nox has provisional support for running on Windows. However, depending on your Windows, Python, and virtualenv versions there may be issues. See the following threads for more info:

Converting from tox

Nox has experimental support for converting tox.ini files into 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

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

pip install --upgrade nox-automation[tox_to_nox]

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


This will create a 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 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.