Configuration & API


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

Defining sessions


Designate the decorated function as a session.

Nox sessions are configured via standard Python functions that are decorated with @nox.session or start with session_. For example, these are all sessions:

import nox

def session_a(session):

def session_123(session):

def b(session):

These are not:

def some_session(session):

def other_func(session):

You may define sessions using either the decorator or the naming convention. This can affect the execution order as described in the usage docs.

You can also parametrize sessions as described in parametrized sessions.

Configuring sessions

Nox will call your session functions with a SessionConfig object. You use this object to tell nox how to create your session and which actions to run. Session configuration is declarative, nox runs your session function first to gather the list of things to do, then executes them separately.

class SessionConfig(posargs=None)

SessionConfig is passed into the session function defined in the user’s The session function uses this object to configure the virtualenv and tell nox which commands to run within the session.

cd(dir, debug=False)

Set the working directory for any commands that run in this session after this point.

cd() is an alias for chdir().

chdir(dir, debug=False)

Set the working directory for any commands that run in this session after this point.

cd() is an alias for chdir().

env = None

A dictionary of environment variables to pass into all commands.

error(*args, **kwargs)

Immediately aborts the session and optionally logs an error.


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

To install packages directly:

session.install('requests', 'mock')

To install packages from a requirements.txt file:

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

To install the current package:

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

None or a string indicating the name of the Python interpreter to use in the session’s virtualenv. If None, the default system interpreter is used.

log(*args, **kwargs)

Outputs a log during the session.


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 appropropriate string or using the function object.
posargs = None

None or a list of strings. This is set to any extra arguments passed to nox on the commandline.

reuse_existing_virtualenv = None

A boolean indicating whether to recreate or reuse the session’s virtualenv. If True, then any existing virtualenv will be used. This can also be specified globally using the --reuse-existing-virtualenvs argument when running nox.

run(*args, **kwargs)

Schedule a command or function to in the session.

Commands must be specified as a list of strings, for example:'py.test', '-k', 'fast', 'tests/')'flake8', '--import-order-style=google')

You can not just pass everything as one string. For example, this will not work:'py.test -k fast tests/')

You can set environment variables for the command using env:
    '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:
    'py.test', '-k', 'not slow',
    success_codes=[0, 5])
  • env (dict or None) – A dictionary of environment variables to expose to the command. By default, all evironment 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.

Functions can be scheduled just by passing the function and any args, just like functools.partial():, 'docs/_build')
skip(*args, **kwargs)

Immediately skips the session and optionally logs a warning.

virtualenv = None

A boolean indicating whether or not to create a virtualenv. Defaults to True.

virtualenv_dirname = None

An optional string that determines the name of the directory where the virtualenv will be created. This is relative to the –envdir option passed into the nox command. By default, nox will generate the name based on the function signature.