Skip to content

Create a run#

Use the init_run() function to create a new run.

The following code starts a new Neptune run in the project specified by the NEPTUNE_PROJECT environment variable:

import neptune

run = neptune.init_run()
If Neptune can't find your project name or API token

As a best practice, you should save your Neptune API token and project name as environment variables:

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jvYh3Kb8"
export NEPTUNE_PROJECT="ml-team/classification"

You can, however, also pass them as arguments when initializing Neptune:

run = neptune.init_run(
    api_token="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jvYh3Kb8",  # your token here
    project="ml-team/classification",  # your full project name here
  • API token: In the bottom-left corner, expand the user menu and select Get my API token.
  • Project name: in the top-right menu: Edit project details.

If you haven't registered, you can also log anonymously to a public project (make sure not to publish sensitive data through your code!):

run = neptune.init_run(

The started run is now tracking some system metrics in the background, plus whatever metadata you log in your code. By default, Neptune periodically synchronizes the data with the servers in the background.

The connection to Neptune remains open until the run is stopped or the script finishes executing.

Stop the run when done

Once you are done logging, you should stop the connection to the Neptune run. When logging from a Jupyter notebook or other interactive environments, you need to do this manually:


If you're running a script, the connection is stopped automatically when the script finishes executing. In interactive sessions, however, the connection to Neptune is only stopped when the kernel stops.

Additional init_run() keyword arguments#

You can use a number of additional arguments to control aspects of your run.

For example:

run = neptune.init_run(
    name="First BERT",  # (1)!
    description="First BERT run for NLP project",  # (2)!
    mode=debug,  # (3)!
    tags=["huggingface", "test", "BERT"],  # (4)!
    source_files=["", ""],  # (5)!
    capture_hardware_metrics=False,  # (6)!
  1. Add a custom name for the run. It's displayed in the app, where it can also be edited.
  2. Add free-form text that describes the run. It's displayed and editable in the app.
  3. Set the mode for the metadata tracking. To learn more about modes, see Connection modes reference.
  4. Tags help you keep runs organized. You can see and manage tags in the app as well. For details, see Add tags.
  5. Specify exactly which source files to log for the run (the default is to log the script that was executed).
  6. Turn certain auto-logged metrics off. For more info, see What is logged automatically.


For the full list of run arguments you can use, see API referenceinit_run()