Aim

3.29.1 · active · verified Thu Apr 16

Aim is an open-source, self-hosted AI metadata and ML experiment tracking tool that helps record, search, and compare AI experiments. It provides a performant UI for exploring and comparing runs and an SDK for programmatic access to tracked metadata. As of version 3.29.1, it continues to release frequent minor updates and bug fixes, typically multiple times per year, within its major version. [1, 12, 18]

Common errors

```
ERROR: Could not find a version that satisfies the requirement aimrocks==X.X.X (from aim) (from versions: ...)
```
cause The `aimrocks` dependency, a core component, often fails to build or find pre-compiled wheels for certain operating systems (especially Windows) or Python versions (e.g., Python 3.13) during `pip install aim`. [17, 26]

fix Try installing Aim in a Linux environment (e.g., using WSL on Windows) or a Python version for which pre-compiled `aimrocks` wheels are available. Consult Aim's GitHub issues for known compatible environments or workarounds. [17, 23, 26]
```
ERROR Too many open files
```
cause This error typically indicates that the operating system limit for open file descriptors has been reached, which can happen with long-running Aim experiments or numerous parallel runs, as Aim uses a file-based storage backend. [25]

fix Increase the operating system's file descriptor limit (e.g., `ulimit -n <new_limit>` on Linux) before running Aim experiments. A common recommendation is to set it to a higher value like 65536. Consult your OS documentation for persistent changes. [25]

Warnings

breaking Upgrading from Aim 2.x to Aim 3.x involves significant breaking changes due to a completely revamped Python SDK and UI, along with a new underlying storage implementation. Direct migration of older logs may require custom scripts. [13]
Fix: Refer to the official Aim documentation for migration guides and updated API usage when moving from Aim 2.x to 3.x. It's recommended to start new projects with Aim 3.x's API. [13]
gotcha Aim relies on the `aimrocks` dependency, which can cause installation failures on Windows, especially with newer Python versions (e.g., Python 3.13) or specific environments. [17, 23, 26]
Fix: If encountering `aimrocks` installation errors, consider using a Linux environment (including WSL on Windows) or a Python version known to be compatible (e.g., Python 3.10-3.12 as of Aim 3.21). Check Aim's GitHub issues for the latest compatibility updates. [17, 20, 26]
gotcha When using Aim's remote tracking server, you must explicitly specify the remote repository URL (e.g., `aim://localhost:53800`) when initializing a Run, and ensure proper port-forwarding or network access to the server. [2]
Fix: Initialize runs with `run = Run(repo="aim://<host>:<port>")` and ensure the server port is accessible (e.g., `kubectl port-forward <aim-server-pod> 53800:53800` for Kubernetes). [2]

Install

pip install aim Install Aim

Imports

Run
```
from aim import Run
```
The primary class for initializing and managing an Aim experiment run.

Quickstart

This quickstart demonstrates how to initialize an Aim run, log hyperparameters, and track metrics. After running this script, navigate to your project directory in the terminal and run `aim up` to launch the Aim UI and visualize your experiment results. [1, 12]

import aim
import math

# Initialize a new run
run = aim.Run()

# Log hyper-parameters
run["hparams"] = {
    "learning_rate": 0.001,
    "batch_size": 32,
    "optimizer": "Adam"
}

# Log metrics
for step in range(100):
    run.track(math.sin(step / 10.0), name='sine', step=step)
    run.track(math.cos(step / 10.0), name='cosine', step=step)

print(f"Aim run created with hash: {run.hash}. Start UI with 'aim up'.")

view raw JSON →