Get started

Learn how to install and configure Neptune for logging metadata to your project.

note

Neptune is currently available only to select customers. If you don't yet have access, you can:

• Request a free trial
• Explore Neptune features in a live demo project

Prerequisites

Software	Version	Website
Python	3.9+	python.org/downloads
pip	-	pip.pypa.io

1. Create a project

A project is where you send your run metadata. It typically represents one machine learning task.

1. Log in to your Neptune workspace.

2. Create a project or choose an existing one.

2. Get the project path

To send the metadata to the right place, Neptune requires you to specify the project path in the following format: workspace-name/project-name.

To get your project path:

1. In the Neptune app, open the project menu ().

2. From the dropdown, select Settings.

   

3. Get your API token

To authenticate with Neptune, get your API token:

1. In the Neptune app, expand the user menu.

2. Select Get your API token.

   

tip

If you're a workspace admin, you can also set up a service account in your workspace settings. This way, multiple people or machines can share the same API token.

4. Save credentials as environment variables

By saving your project path and API token to environment variables, you avoid putting them in your Python code. This approach is more convenient and secure.

Adding an environment variable depends on your system:

Linux

In your .profile or other shell initialization file, use the export commands:

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

export NEPTUNE_PROJECT="workspace-name/project-name"

macOS

In your .profile or other shell initialization file, use the export commands:

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

export NEPTUNE_PROJECT="workspace-name/project-name"

Windows

1. Open a terminal app, such as PowerShell or Command Prompt.

2. Paste the setx commands and press Enter:

   setx NEPTUNE_API_TOKEN "h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ=="

   setx NEPTUNE_PROJECT "workspace-name/project-name"

3. To activate the change, restart the terminal app.

Optionally, add the variable in Settings → Edit the system environment variables.

Jupyter Notebook

In notebooks for your personal use, set credentials with magic commands:

%env NEPTUNE_API_TOKEN=h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ==

%env NEPTUNE_PROJECT=workspace-name/project-name

In shared notebooks, it's more secure to use the os and getpass libraries:

import os
from getpass import getpass

os.environ["NEPTUNE_API_TOKEN"] = getpass("Enter your Neptune API token: ")
os.environ["NEPTUNE_PROJECT"] = "workspace-name/project-name"

Note that these don't persist when the notebook kernel is terminated. You must declare the variables again if you restart the notebook.

Google Colab

In Colab notebooks for your personal use, set credentials with magic commands:

%env NEPTUNE_API_TOKEN=h0dHBzOi8aHR0cHM.4kl0jvYh3Kb8...ifQ==

%env NEPTUNE_PROJECT=workspace-name/project-name

In shared Colab notebooks, it's more secure to use the os and getpass libraries:

import os
from getpass import getpass

os.environ["NEPTUNE_API_TOKEN"] = getpass("Enter your Neptune API token: ")
os.environ["NEPTUNE_PROJECT"] = "workspace-name/project-name"

Note that these don't persist when the notebook kernel is terminated. You must declare the variables again if you restart the notebook.

You may need to restart terminal session. After this, Neptune finds your credentials automatically.

5. Install Neptune

Install the neptune-scale package:

pip install neptune-scale

You're ready to start using Neptune! If you need help, contact support@neptune.ai.

Next steps

• Create a run
• Quickstart – log some mocked metadata and explore it in the Neptune app.