Quickstart

pipconda

pip install neptune

conda install -c conda-forge neptune

Installing through Anaconda Navigator

To find neptune, you may need to update your channels and index.

1. In the Navigator, select Environments.
2. In the package view, click Channels.
3. Click Add..., enter conda-forge, and click Update channels.
4. In the package view, click Update index... and wait until the update is complete. This can take several minutes.
5. You should now be able to search for neptune.

Note: The displayed version may be outdated. The latest version of the package will be installed.

Note: On Bioconda, there is a "neptune" package available which is not the neptune.ai client library. Make sure to specify the "conda-forge" channel when installing neptune.ai.

(Optional) Register and create a project

1. Sign up for a Neptune account: neptune.ai/register
2. In your Neptune workspace, navigate to All projects → New project.

3. Enter the details and select Create.

   For more help, see Create a project.

Create a run

1. (Optional steps, to follow the Quickstart example)

   Install mnist:

   pip install mnist
   

   Download the sample image (or use your own):

   curl -O https://neptune.ai/wp-content/uploads/2023/06/Lenna_test_image.png
   

2. Create a script called hello_neptune.py.

3. 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 object
run = neptune.init_run(
    project="your-workspace-name/your-project-name",  # (1)!
    api_token="YourNeptuneApiToken",  # (2)!
    tags=["quickstart", "script"],  # optional
)

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

# Log 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 single image to Neptune
run["single_image"].upload("Lenna_test_image.png")

# Download MNIST dataset
import mnist

train_images = mnist.train_images()
train_labels = mnist.train_labels()

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

for i in range(10):
    run["image_series"].append(
        File.as_image(
            train_images[i] / 255
        ),  # You can upload arrays as images using the File.as_image() method
        name=f"{train_labels[i]}",
    )

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

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

   To copy it, navigate to the project settings in the top-right () and select Edit project details.

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!

hello_neptune.py

import neptune

# Create a Neptune run object
run = neptune.init_run(
    project="common/quickstarts",  # (1)!
    api_token=neptune.ANONYMOUS_API_TOKEN,  # (2)!
    tags=["quickstart", "script"],  # optional
)

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

# Log 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 single image to Neptune
run["single_image"].upload("Lenna_test_image.png")

# Download MNIST dataset
import mnist

train_images = mnist.train_images()
train_labels = mnist.train_labels()

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

for i in range(10):
    run["image_series"].append(
        File.as_image(
            train_images[i] / 255
        ),  # You can upload arrays as images using the File.as_image() method
        name=f"{train_labels[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, "ml-team/classification".

   To copy the name, click the menu in the top-right corner and select Edit project details.

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

   Once you register, you should leave the token out of your script and instead save it as an environment variable.

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/common/quickstarts/e/QUI-1/metadata

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(
    api_token=neptune.ANONYMOUS_API_TOKEN,
    project="common/quickstarts",
)

Explore the results

In the Run details view, you can browse your data in the following tabs:

• All metadata - displays logged metadata in a folder-like structure.
• Charts - visualizes the metrics as charts.
• Images - displays any logged images.
• Monitoring - shows hardware consumption during the run execution.
• Source code - snapshots code and Git information.

Browse example runs in Neptune  See code on GitHub 

Next steps

• Rerun the script with different values to track a few more runs, then select the Compare runs tab to compare and visualize them.
• Before moving on, take a moment to save your API token as an environment variable. This helps keep your API token secure, as you can omit the api_token parameter from your code.
  • Export the project name as an environment variable, too.
• 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

• Using Neptune ≫ Add Neptune to your code
• Using Neptune ≫ What you can log and display
• Use cases ≫ Track and organize model-training runs
• Integrations