Skip to content

Creating a run#

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

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

import as 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.

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
  • Find and copy your API token by clicking your avatar and selecting Get my API token.
  • Find and copy your project name in the project SettingsProperties.

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 Neptune run. You need to do this manually when logging from a Jupyter notebook or other interactive environment:


If you're running a script, the connection is stopped automatically when the script finishes executing. In notebooks, however, the connection to Neptune is not stopped when the cell has finished executing, but rather when the entire notebook 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 Adding 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()