# Tutorial

This tutorial will walk you through installing, configuring, and running Nox.

## Installation

Nox can be easily installed via pip:

    python3 -m install nox

You may want to use the user site to avoid messing with your global Python install:

    python3 -m pip install --user nox

Or you can be extra fancy and use pipx:

    pipx install nox

Either way, Nox is usually installed globally, similar to `tox`, `pip`, and other similar tools.

If you’re interested in running `nox` within docker, you can use the thekevjames/nox images on DockerHub which contain builds for all `nox` versions and all supported `python` versions.

## Writing the configuration file

Nox is configured via a file call `noxfile.py` in your project’s directory. This file is a Python file that defines a set of sessions. A session is an environment and a set of commands to run in that environment. If you’re familiar with tox sessions are analogous to environments. If you’re familiar with GNU Make, sessions are analogous to targets.

Sessions are declared using the `@nox.session` decorator. This is similar to how Flask uses `@app.route`.

Here’s a basic Noxfile that runs flake8 against `example.py` (you can create `example.py` yourself):

    import nox

    @nox.session
    def lint(session):
        session.install("flake8")
        session.run("flake8", "example.py")

## Running Nox for the first time

Now that you’ve installed Nox and have a Noxfile you can run Nox! Open your project’s directory in a terminal and run `nox`. You should see something like this:

    $ nox
    nox > Running session lint
    nox > Creating virtualenv using python3.7 in .nox/lint
    nox > pip install flake8
    nox > flake8 example.py
    nox > Session lint was successful.

✨ You’ve now successfully used Nox for the first time! ✨

The rest of this tutorial will take you through other common things you’ll likely want to do with Nox. You can also jump to into Command-line usage and Configuration & API docs if you want.

## Installing dependencies

Nox more or less passes `session.install` through to `pip`, so you can install stuff in the usual way. Here’s some examples:

To install one or more packages at a time:

    @nox.session
    def tests(session):
        # same as pip install pytest protobuf>3.0.0
        session.install("pytest", "protobuf>3.0.0")
        ...

To install a `requirements.txt` file:

    @nox.session
    def tests(session):
        # same as pip install -r -requirements.txt
        session.install("-r", "requirements.txt")
        ...

If your project is a Python package and you want to install it:

    @nox.session
    def tests(session):
        # same as pip install .
        session.install(".")
        ...

## Running commands

The `session.run` function lets you run commands within the context of your session’s virtual environment. Here’s a few examples:

You can install and run Python tools:

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

If you want to pass more arguments to a program just add more arguments to `run`:

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

You can also pass environment variables:

    @nox.session
    def tests(session):
        session.install("black")
        session.run(
            "pytest",
            env={
                "FLASK_DEBUG": "1"
            }
        )

See `nox.sessions.Session.run()` for more options and examples for running programs.

## Selecting which sessions to run

Once you have multiple sessions in your Noxfile you’ll notice that Nox will run them all by default. While this is useful, it often useful to just run one or two at a time. You can use the `--sessions` argument (or `-s`) to select which sessions to run. You can use the `--list` argument to show which sessions are available and which will be run. Here’s some examples:

Here’s a Noxfile with three sessions:

    import nox

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

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

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

If you just run `nox --list` you’ll see that all sessions are selected:

    Sessions defined in noxfile.py:

    * test
    * lint
    * docs

    sessions marked with * are selected,
    sessions marked with - are skipped.

If you run `nox --list --sessions lint` you’ll see that only the lint session is selected:

    Sessions defined in noxfile.py:

    - test
    * lint
    - docs

    sessions marked with * are selected,
    sessions marked with - are skipped.

And if you run `nox --sessions lint` Nox will just run the lint session:

    nox > Running session lint
    nox > Creating virtualenv using python3 in .nox/lint
    nox > ...
    nox > Session lint was successful.

There are many more ways to select and run sessions! You can read more about invoking Nox in Command-line usage.

## Testing against different and multiple Pythons

Many projects need to support either a specific version of Python or multiple Python versions. You can have Nox run your session against multiple interpreters by specifying `python` to `@nox.session`. Here’s some examples:

If you want your session to specifically run against a single version of Python only:

    @nox.session(python="3.7")
    def test(session):
        ...

If you want your session to run against multiple versions of Python:

    @nox.session(python=["2.7", "3.5", "3.7"])
    def test(session):
        ...

You’ll notice that running `nox --list` will show that this one session has been expanded into three distinct sessions:

    Sessions defined in noxfile.py:

    * test-2.7
    * test-3.5
    * test-3.7

You can run all of the `test` sessions using `nox --sessions test` or run an individual one using the full name as displayed in the list, for example, `nox --sessions test-3.5`. More details on selecting sessions can be found over in the Command-line usage documentation.

You can read more about configuring the virtual environment used by your sessions over at Configuring a session’s virtualenv.

## Parametrization

Just like Nox can handle running against multiple interpreters, Nox can also handle running your sessions with a list of different arguments using the `nox.parametrize()` decorator.

Here’s a short example of using parametrization to test against two different versions of Django:

    @nox.session
    @nox.parametrize("django", ["1.9", "2.0"])
    def test(session, django):
        session.install(f"django=={django}")
        session.run("pytest")

If you run `nox --list` you’ll see that Nox expands your one session into multiple sessions. One for each argument value that you want to be passed to your session:

    Sessions defined in noxfile.py:

    * test(django='1.9')
    * test(django='2.0')

`nox.parametrize()` has an interface and usage intentionally similar to pytest’s parametrize. It’s an extremely powerful feature of Nox. You can read more about parametrization and see more examples over at Parametrizing sessions.

## Next steps

Look at you! You’re now basically an expert at Nox! ✨

For this point you can:

- Read more docs, such as Command-line usage and Configuration & API.
- Give us feedback or contribute, see <no title>.

Have fun! 💜