Quickstart

This quickstart guide shows how to install Neptune, use some basic logging functions, and inspect the results. We use mocked metrics, the MNIST dataset, and a sample image.

We recommend using your own Neptune project and API token, but you can also run the quickstart without registering.

Create a project

1. Sign up for a Neptune account: neptune.ai/register

2. In the left sidebar, click .

   For help, see Create a project.

Install Neptune

pip install neptune

Prepare the sample data

To access the MNIST dataset, install TensorFlow:

pip install tensorflow

To have a file to upload to Neptune, download the sample image to the location where you'll run the code:

Terminal Jupyter Notebook

curl -o sample.png https://neptune.ai/wp-content/uploads/2024/05/blog_feature_image_046799_8_3_7_3-4.jpg

! curl -o sample.png https://neptune.ai/wp-content/uploads/2024/05/blog_feature_image_046799_8_3_7_3-4.jpg

Create a run

1. Create a script called hello_neptune.py.
2. Copy and paste the below code into the script file:

Using your own projectLogging without registration

hello_neptune.py

import neptune

# Create a Neptune run
run = neptune.init_run(
    project="your-workspace-name/your-project-name", # (1)!
    api_token="YourNeptuneApiToken", # (2)!
    name="sincere-oxpecker", # (3)!
    tags=["quickstart", "script"], # (4)!
    dependencies="infer", # (5)!
    monitoring_namespace="monitoring", # (6)!
)

# Log a single value
# Specify a field name ("seed") inside the run and assign a value to it
run["seed"] = 0.42

# Log a series of values
from random import random

epochs = 10
offset = random() / 5

for epoch in range(epochs):
    acc = 1 - 2**-epoch - random() / (epoch + 1) - offset
    loss = 2**-epoch + random() / (epoch + 1) + offset

    run["accuracy"].append(acc)
    run["loss"].append(loss)

# Upload an image
run["single_image"].upload("sample.png")

# Load the MNIST dataset
from tensorflow.keras.datasets import mnist

(x_train, y_train), (x_test, y_test) = mnist.load_data()

# Upload a series of images
from neptune.types import File

for i in range(10):
    run["image_series"].append(
        File.as_image(
            x_train[i]
        ),  # You can upload arrays as images using Neptune's File.as_image() method
        name=str(y_train[i]),
    )

# Stop the connection and synchronize the data with the Neptune servers
run.stop()

1. The full project name. For example, "ml-team/classification".

   • You can copy the name from the project details ( → Details & privacy)
   • You can also find a pre-filled project string in Experiments → Create a new run.

2. In the bottom-left corner of the Neptune app, expand the user menu and select Get your API token.

   When you're done testing, save your API token as an environment variable instead of putting it here in the code!

3. Sets a custom name, which you can use as a human-friendly ID.

   To display it in the app, add sys/name as a column.

   You can also edit the name in the run information view ( → Run information).

4. Tags help organize and compare runs. You can also manage tags in the Neptune web app.

5. You can also pass the path to your dependencies file or omit this parameter.

6. Optional, but recommended. See Best practices: Monitoring system metrics.

hello_neptune.py

import neptune

# Create a Neptune run
run = neptune.init_run(
    project="common/quickstarts", # (1)!
    api_token=neptune.ANONYMOUS_API_TOKEN, # (2)!
    name="sincere-oxpecker", # (3)!
    tags=["quickstart", "script"], # (4)!
    dependencies="infer", # (5)!
    monitoring_namespace="monitoring", # (6)!
)

# Log a single value
# Specify a field name ("seed") inside the run and assign a value to it
run["seed"] = 0.42

# Log a series of values
from random import random

epochs = 10
offset = random() / 5

for epoch in range(epochs):
    acc = 1 - 2**-epoch - random() / (epoch + 1) - offset
    loss = 2**-epoch + random() / (epoch + 1) + offset

    run["accuracy"].append(acc)
    run["loss"].append(loss)

# Upload an image
run["single_image"].upload("sample.png")

# Load the MNIST dataset
from tensorflow.keras.datasets import mnist

(x_train, y_train), (x_test, y_test) = mnist.load_data()

# Upload a series of images
from neptune.types import File

for i in range(10):
    run["image_series"].append(
        File.as_image(
            x_train[i]
        ),  # You can upload arrays as images using Neptune's File.as_image() method
        name=str(y_train[i]),
    )

# Stop the connection and synchronize the data with the Neptune servers
run.stop()

1. Projects in the common workspace are public and can be used for testing.

   To log to your own workspace, pass the full name of your Neptune project: workspace-name/project-name. For example, project="ml-team/classification".

   You can copy the name from the project details ( → Details & privacy).

2. The api_token argument is included to enable anonymous logging.

   Once you've registered, leave the token out of your script and instead save it as an environment variable.

3. Sets a custom name, which you can use as a human-friendly ID.

   To display it in the app, add sys/name as a column.

   You can also edit the name in the run information view ( → Run information).

4. Tags help organize and compare runs. You can also manage tags in the Neptune web app.

5. You can also pass the path to your dependencies file or omit this parameter.

6. Optional, but recommended. See Best practices: Monitoring system metrics.

Now that you have your Hello Neptune script ready, execute it from your terminal, Jupyter Lab, or other environments:

python hello_neptune.py

Click the link in the console output to open the run in Neptune.

Example link

https://app.neptune.ai/team-alpha/project-x/e/X-1

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="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jv...Yh3Kb8"

export NEPTUNE_PROJECT="ml-team/classification"

Alternatively, you can pass the information when using a function that takes api_token and project as arguments:

run = neptune.init_run(
    api_token="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jv...Yh3Kb8", # (1)!
    project="ml-team/classification", # (2)!
)

1. In the bottom-left corner, expand the user menu and select Get my API token.
2. You can copy the path from the project details ( → Details & privacy).

If you haven't registered, you can log anonymously to a public project:

api_token=neptune.ANONYMOUS_API_TOKEN
project="common/quickstarts"

Make sure not to publish sensitive data through your code!

Explore the results

In the Neptune web app, you can see the logged metadata appear in real time.

Browse your data in the following tabs:

All metadata – all of the logged metadata, in a folder-like structure.

Charts – metrics visualized as graphs.

Images – previews and interactive galleries.

Monitoring – hardware consumption during the run execution.

Dashboards – custom widgets with saved configurations.

Browse example run in Neptune  See code on GitHub 

Next steps

• Rerun the script with different values to track a few more runs, then toggle the eye icons ( ) to compare the runs. See example in Neptune →

• Before moving on, take a moment to save your Neptune credentials as environment variables.

  This helps keep your API token secure, as you can omit the api_token parameter from your code.

• To get the most out of Neptune, take the Neptune tutorial. It walks you through all of the above plus the central Neptune features.

Other resources to check out

• Add Neptune to your code
• What you can log and display
• Onboarding guide for teams
• Integrations