Configuration & API¶

Noxfile¶

Nox looks for configuration in a file named noxfile.py by default. You can specify a different file using the --noxfile argument when running nox.

Defining sessions¶

session(func=None, python=None, py=None, reuse_venv=None)¶: Designate the decorated function as a session.

Nox sessions are configured via standard Python functions that are decorated with @nox.session. For example:

import nox

@nox.session
def tests(session):
    session.run('pytest')

You can also configure sessions to run against multiple Python versions as described in Configuring a session’s virtualenv and parametrize sessions as described in parametrized sessions.

Session description¶

You can add a description to your session using a docstring. The first line will be shown when listing the sessions. For example:

import nox

@nox.session
def tests(session):
    """Run the test suite."""
    session.run('pytest')

The nox -l command will show:

$ nox -l
Available sessions:
* tests -> Run the test suite.

Configuring a session’s virtualenv¶

By default, Nox will create a new virtualenv for each session using the same interpreter that Nox uses. If you installed Nox using Python 3.6, Nox will use Python 3.6 by default for all of your sessions.

You can tell Nox to use a different Python interpreter/version by specifying the python argument (or its alias py) to @nox.session:

@nox.session(python='2.7')
def tests(session):
    pass

You can also tell Nox to run your session against multiple Python interpreters. Nox will create a separate virtualenv and run the session for each interpreter you specify. For example, this session will run twice - once for Python 2.7 and once for Python 3.6:

@nox.session(python=['2.7', '3.6'])
def tests(session):
    pass

When you provide a version number, Nox automatically prepends python to determine the name of the executable. However, Nox also accepts the full executable name. If you want to test using pypy, for example:

@nox.session(python=['2.7', '3.6', 'pypy-6.0'])
def tests(session):
    pass

When collecting your sessions, Nox will create a separate session for each interpreter. You can see these sesions when running nox --list-sessions. For example this Noxfile:

@nox.session(python=['2.7', '3.5', '3.6', '3.7'])
def tests(session):
    pass

Will produce these sessions:

* tests-2.7
* tests-3.5
* tests-3.6
* tests-3.7

Note that this expansion happens before parameterization occurs, so you can still parametrize sessions with multiple interpreters.

If you want to disable virtualenv creation altogether, you can set python to False:

@nox.session(python=False)
def tests(session):
    pass

Finally you can also specify that the virtualenv should always be reused instead of recreated every time:

@nox.session(
    python=['2.7', '3.6'],
    reuse_venv=True)
def tests(session):
    pass

Using the session object¶

Nox will call your session functions with a Session object. You use this object to to run various commands in your session.

class Session(runner)¶

The Session object is passed into each user-defined session function.

This is your primary means for installing package and running commands in your Nox session.

property bin¶: The bin directory for the virtualenv.

cd(dir)¶: An alias for chdir().

chdir(dir)¶: Change the current working directory.

property env¶: A dictionary of environment variables to pass into all commands.

error(*args, **kwargs)¶: Immediately aborts the session and optionally logs an error.

install(*args, **kwargs)¶

Install invokes pip to install packages inside of the session’s virtualenv.

To install packages directly:

session.install('py.test')
session.install('requests', 'mock')
session.install('requests[security]==2.9.1')

To install packages from a requirements.txt file:

session.install('-r', 'requirements.txt')
session.install('-r', 'requirements-dev.txt')

To install the current package:

session.install('.')
# Install in editable mode.
session.install('-e', '.')

Additional keyword args are the same as for run().

log(*args, **kwargs)¶: Outputs a log during the session.

notify(target)¶

Place the given session at the end of the queue.

This method is idempotent; multiple notifications to the same session have no effect.

Parameters:: target (Union[str, Callable]) – The session to be notified. This may be specified as the appropriate string (same as used for nox -s) or using the function object.

property posargs¶: This is set to any extra arguments passed to nox on the commandline.

property python¶: The python version passed into @nox.session.

run(*args, env=None, **kwargs)¶

Run a command.

Commands must be specified as a list of strings, for example:

session.run('py.test', '-k', 'fast', 'tests/')
session.run('flake8', '--import-order-style=google')

You can not just pass everything as one string. For example, this will not work:

session.run('py.test -k fast tests/')

You can set environment variables for the command using env:

session.run(
    'bash', '-c', 'echo $SOME_ENV',
    env={'SOME_ENV': 'Hello'})

You can also tell nox to treat non-zero exit codes as success using success_codes. For example, if you wanted to treat the py.test “tests discovered, but none selected” error as success:

session.run(
    'py.test', '-k', 'not slow',
    success_codes=[0, 5])

Parameters:

env (dict or None) – A dictionary of environment variables to expose to the command. By default, all environment variables are passed.
silent (bool) – Silence command output, unless the command fails. False by default.
success_codes (list, tuple, or None) – A list of return codes that are considered successful. By default, only 0 is considered success.
external (bool) – If False (the default) then programs not in the virtualenv path will cause a warning. If True, no warning will be emitted. These warnings can be turned into errors using --error-on-external-run. This has no effect for sessions that do not have a virtualenv.

skip(*args, **kwargs)¶: Immediately skips the session and optionally logs a warning.

property virtualenv¶: The virtualenv that all commands are run in.

Modifying Nox’s behavior in the Noxfile¶

Nox has various command line arguments that can be used to modify its behavior. Some of these can also be specified in the Noxfile using nox.options. For example, if you wanted to store Nox’s virtualenvs in a different directory without needing to pass it into nox every time:

import nox

nox.options.envdir = ".cache"

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

Or, if you wanted to provide a set of sessions that are run by default:

import nox

nox.options.sessions = ["lint", "tests-3.6"]

...

The following options can be specified in the Noxfile:

nox.options.envdir is equivalent to specifying –envdir.
nox.options.sessions is equivalent to specifying -s or –sessions.
nox.options.keywords is equivalent to specifying -k or –keywords.
nox.options.reuse_existing_virtualenvs is equivalent to specifying –reuse-existing-virtualenvs. You can force this off by specifying --no-reuse-existing-virtualenvs during invocation.
nox.options.stop_on_first_error is equivalent to specifying –stop-on-first-error. You can force this off by specifying --no-stop-on-first-error during invocation.
nox.options.error_on_missing_interpreters is equivalent to specifying –error-on-missing-interpreters. You can force this off by specifying --no-error-on-missing-interpreters during invocation.
nox.options.error_on_external_run is equivalent to specifying –error-on-external-run. You can force this off by specifying --no-error-on-external-run during invocation.
nox.options.report is equivalent to specifying –report.

When invoking nox, any options specified on the command line take precedence over the options specified in the Noxfile. If either --sessions or --keywords is specified on the command line, both options specified in the Noxfile will be ignored.