Creating, organizing & sharing visualizations of live, rich data. Supports Python.

Jump To: Setup, Usage, API, Customizing, Contributing, License

Visdom aims to facilitate visualization of (remote) data with an emphasis on supporting scientific experimentation.
Broadcast visualizations of plots, images, and text for yourself and your collaborators. Organize your visualization space programmatically or through the UI to create dashboards for live data, inspect results of experiments, or debug experimental code.

Concepts

Setup

Install from pip

> pip install visdom

Install from source

> pip install git+https://github.com/fossasia/visdom

Optional: To save Plotly figures to image files from code (e.g. PNG/SVG) without using the browser download button, install plotly and kaleido: pip install plotly kaleido. See vis.plotlyplot and vis.save_plotly_figure.

Usage

Start the server (probably in a screen or tmux) from the command line:

> visdom

Visdom now can be accessed by going to http://localhost:8097 in your browser, or your own host address if specified.

The visdom command is equivalent to running python -m visdom.server.

If the above does not work, try using an SSH tunnel to your server by adding the following line to your local ~/.ssh/config:

1. -port : The port to run the server on.
2. -hostname : The hostname to run the server on.
3. -base_url : The base server url (default = /).
4. -env_path : The path to the serialized session to reload.
5. -logging_level : Logging level (default = INFO). Accepts both standard text and numeric logging values.
6. -readonly : Flag to start server in readonly mode.
7. -enable_login : Flag to setup authentication for the server, requiring a username and password to login.
8. -force_new_cookie : Flag to reset the secure cookie used by the server, invalidating current login cookies.

1. -bind_local : Flag to make the server accessible only from localhost.
2. -eager_data_loading : By default visdom loads environments lazily upon user request. Setting this flag lets visdom pre-fetch all environments upon startup.

VISDOM_USERNAME=username
VISDOM_PASSWORD=password
VISDOM_USE_ENV_CREDENTIALS=1 visdom -enable_login

# Generate a self-signed certificate (for development only)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
Start the server with HTTPS
python -m visdom.server -ssl_certfile cert.pem -ssl_keyfile key.pem

Access the server at https://localhost:8097.

# For Production - real CA-signed certificate (default)
vis = visdom.Visdom(server="https://myserver.com")

For Development - self signed certificate
vis = visdom.Visdom(server="https://localhost", ssl_verify=False)

Note: ssl_verify=False disables certificate verification and should only be used in development with self-signed certificates. Do not use in production.

import visdom
import numpy as np
vis = visdom.Visdom()
vis.text('Hello, world!')
vis.image(np.ones((3, 10, 10)))

python example/demo.py

The same showcase for the asyncio client — concurrent plots, a single-request append loop and a coroutine event handler — is in example/async_demo.py; see Async usage.

python example/async_demo.py

• server: the hostname of your visdom server (default: 'http://localhost')
• port: the port for your visdom server (default: 8097)
• base_url: the base visdom server url (default: /)
• env: Default environment to plot to when no env is provided (default: main)
• raise_exceptions: Raise exceptions upon failure rather than printing them (default: True (soon))
• log_to_filename: If not none, log all plotting and updating events to the given file (append mode) so that they can be replayed later using replay_log (default: None)
• use_incoming_socket: enable use of the socket for receiving events from the web client, allowing user to register callbacks (default: True)
• http_proxy_host: Deprecated. Use Proxies argument for complete proxy support.
• http_proxy_port: Deprecated. Use Proxies argument for complete proxy support.
• username: username to use for authentication, if server started with -enable_login (default: None)
• password: password to use for authentication, if server started with -enable_login (default: None)
• proxies: Dictionary mapping protocol to the URL of the proxy (e.g. {http: foo.bar:3128}) to be used on each Request. (default: None)
• offline: Flag to run visdom in offline mode, where all requests are logged to file rather than to the server. Requires log_to_filename is set. In offline mode, all visdom commands that don't create or update plots will simply return True. (default: False)
• use_preflight_checks: Ask the server whether a window exists before an update='append' or a store_history=True frame, which costs a second round trip per call. Set it to False to send one request and let the server create the window if it isn't there -- roughly halving the requests of an append loop. Requires a server new enough to lay out a window it creates from an append; against an older one such a window comes out unstyled. (default: True)

import asyncio
import numpy as np
from visdom.async_client import AsyncVisdom
async def main():
    vis = await AsyncVisdom.create(server="http://localhost", port=8097)
    async with vis:
        await asyncio.gather(
            vis.line(Y=np.random.rand(20), win="a"),
            vis.line(Y=np.random.rand(20), win="b"),
        )
asyncio.run(main())

Every plotting method of Visdom is available with the same name, the same arguments and the same return value — as a coroutine. Nothing is reimplemented: the method bodies run as the synchronous code they already are, on a thread pool the client owns, and only the request itself is asynchronous. That is also why the CPU-heavy encodes (image, matplot) stay off your event loop for free.

• Build it with create, not (). Connecting means a POST and __init__ cannot await. create accepts every Visdom argument, plus max_concurrency (default 10) which sizes both the client's thread pool and the number of requests tornado will start at once. max_concurrency only supplies the default for tornado's max_clients: pass max_clients explicitly and it wins, so the two limits then differ by as much as you asked for.
• shutdown closes the client, close closes a window. close is Visdom.close and keeps its usual meaning, so the method that releases the HTTP client and the worker pool is shutdown(). Using the client as an async context manager calls it for you.
• Two defaults differ from Visdom. use_incoming_socket is False here (most async callers never register a handler, and a backchannel costs a held-open connection plus a thread), and use_preflight_checks is False (an async client is new code talking to a server that understands layout_create, so an append costs one request rather than two). Pass either explicitly to get the synchronous behavior back.
• Concurrency is yours to ask for. gather runs the calls on separate worker threads against one shared inner client, and that client is no more thread-safe than the synchronous one — concurrent calls should target distinct windows.
• Event handlers work, and may be coroutines. Pass use_incoming_socket=True (or use_polling=True for the HTTP fallback) and register as usual with register_event_handler; registration is not a coroutine, since it never reaches the server. A plain handler runs on the client's own single dispatch thread; a coroutine handler has only its wrapper there, and its body runs on your loop, so it can await further calls on the same client. Either way handlers run one at a time, in arrival order.
• No HTTP proxies. create raises NotImplementedError for proxies / http_proxy_host / http_proxy_port: the transport is tornado's AsyncHTTPClient, which has no proxy support without pycurl. Use Visdom behind a proxy.

| Client | plots/s | p50 | p95 | |---|---|---|---| | Visdom, preflight on (default) | 198 | 5.00 ms | 5.73 ms | | Visdom, use_preflight_checks=False | 304 | 3.32 ms | 4.09 ms | | AsyncVisdom, awaited serially | 235 | 4.24 ms | 4.87 ms | | AsyncVisdom, 8 concurrent | 410 | 13.19 ms | 18.33 ms |

example/async_demo.py runs all of the above against a live server.

• vis.image : image
• vis.image_heatmap : image with heatmap overlay
• vis.update_image_slider : set visible frame of an image_history pane
• vis.images : list of images
• vis.text : arbitrary HTML
• vis.properties : properties grid
• vis.table : editable, resizable table pane
• vis.html_table : static styled HTML table
• vis.audio : audio
• vis.video : videos
• vis.svg : SVG object
• vis.matplot : matplotlib plot
• vis.plotlyplot : arbitrary Plotly figure
• vis.embeddings : interactive embedding projection
• vis.save : serialize state server-side

• vis.scatter : 2D or 3D scatter plots
• vis.sunburst : sunburst (hierarchy) charts
• vis.line : line plots
• vis.learning_curve : named training metric curves
• vis.stem : stem plots
• vis.heatmap : heatmap plots
• vis.confusion_matrix : confusion matrix plots
• vis.bar : bar graphs
• vis.histogram : histograms
• vis.histogram2d : 2D histograms (density maps)
• vis.boxplot : boxplots
• vis.violin : violin plots
• vis.pie : pie charts
• vis.surf : surface plots
• vis.contour : contour plots
• vis.roc_curve : ROC curves
• vis.pr_curve : precision-recall curves
• vis.quiver : quiver plots
• vis.mesh : mesh plots
• vis.sankey : sankey (flow) diagrams
• vis.dual_axis_lines : double y axis line plots
• vis.graph : network graphs

import visdom
vis = visdom.Visdom()
trace = dict(x=[1, 2, 3], y=[4, 5, 6], mode="markers+lines", type='custom',
             marker={'color': 'red', 'symbol': 104, 'size': "10"},
             text=["one", "two", "three"], name='1st Trace')
layout = dict(title="First Plot", xaxis={'title': 'x1'}, yaxis={'title': 'x2'})
vis._send({'data': [trace], 'layout': layout, 'win': 'mywin'})

• vis.close : close a window by id
• vis.delete_env : delete an environment by env_id
• vis.win_exists : check if a window already exists by id
• vis.get_env_list : get a list of all of the environments on your server
• vis.get_window_data: get current data for a window
• vis.set_tags: replace or append environment tags
• vis.get_tags: read environment tags
• vis.save_plotly_figure: save a Plotly figure to an image file from code (no browser click)
• vis.check_connection: check if the server is connected
• vis.replay_log: replay the actions from the provided log file

• vis.experiment : create or update experiment metadata for an env
• vis.log_metrics : append metric observations to an env's experiment
• vis.finish_experiment : mark an experiment terminal (finished/failed)
• vis.search_experiments : search experiments across envs with a query
• vis.compare_experiments : diff experiments field by field
• vis.suggest_experiment : suggest parameters for the next run (reserved)
• vis.hparams : open a hyper-parameter pane over the selected runs
• vis.update_hparams : change or refresh an existing hyper-parameter pane

Framework-specific logging bridges that wrap the Visdom API so training loops stay focused on training. Each logger lives in its own submodule and handles window creation, step tracking, and throttling internally. None of the framework packages below are part of Visdom's own install — each logger imports its framework lazily and raises a clear ImportError with the pip install command if it's missing.

Requirements: pip install visdom torch

visdom.pytorch.VisdomLogger is a context manager for raw PyTorch training loops. Call tracker.log(name, value) for any scalar — no viz.line() arguments needed.

import visdom
from visdom.pytorch import VisdomLogger
viz = visdom.Visdom()
with VisdomLogger(viz, env="my_run") as tracker:
    for epoch in range(num_epochs):
        train_loss = run_train_epoch(model, loader)
        val_loss   = run_val_epoch(model, val_loader)
tracker.log("Train Loss", train_loss)
        tracker.log("Val Loss",   val_loss)
        tracker.log("LR",         optimizer.param_groups[0]["lr"])

Per-batch logging with log_every — use when logging inside the batch loop on large datasets:

with VisdomLogger(viz, env="my_run", log_every=50) as tracker:
    for epoch in range(num_epochs):
        for inputs, targets in train_loader:
            loss = criterion(model(inputs), targets)
            optimizer.zero_grad()
            loss.backward()
            optimizer.step()
# sent to Visdom every 50 batches, not every batch
            tracker.log("Train Loss", loss.item(), xlabel="step")
            tracker.log("LR",         optimizer.param_groups[0]["lr"], xlabel="step")

Experiment tracking with params — pass hyperparameters to also record the run as a queryable experiment, alongside the usual charts:

params = {"lr": 1e-2, "batch_size": 32}
with VisdomLogger(viz, env="my_run", params=params) as tracker:
    for epoch in range(num_epochs):
        tracker.log("Train Loss", train_loss)
later, from anywhere
viz.search_experiments("lr < 0.01 AND status = finished")
viz.compare_experiments(["my_run", "my_other_run"])

Tracking is opt-in: without params, VisdomLogger only ever calls viz.line(), unchanged from before this existed. With params, the run's status is recorded as finished on a normal exit or failed if the with-block raised, and every logged metric is mirrored into the experiment alongside the chart it's plotted on.

• viz: a connected visdom.Visdom() instance
• env: environment name (default: auto-generated from timestamp)
• log_every: send every N calls per metric — use with per-batch logging on large datasets (default: 1)
• params: dict of hyperparameters; opts into experiment tracking (default: None, tracking off)

Requirements: pip install visdom lightning (or pip install visdom pytorch-lightning)

visdom.loggers.VisdomLightningLogger implements Lightning's Logger protocol. Lightning aggregates every self.log() / self.log_dict() call in a LightningModule and hands the result to the logger, so nothing in the model or training loop changes — the user passes one logger= argument to Trainer.

import lightning.pytorch as pl
import visdom
from visdom.loggers import VisdomLightningLogger
viz = visdom.Visdom()
logger = VisdomLightningLogger(viz, env="lightning_run")
trainer = pl.Trainer(max_epochs=20, logger=logger, log_every_n_steps=5)
trainer.fit(model, train_loader, val_loader)

Each metric key gets its own window — one key, one line chart, with no train/val name parsing. The epoch key Lightning mixes into the metrics dict is not plotted. How often the logger is called is controlled by Lightning (Trainer(log_every_n_steps=...) for step metrics, once per epoch for epoch metrics).

Hyperparameters passed to self.save_hyperparameters() are rendered once as a properties pane via viz.properties().

Gradient norms come from Lightning, not the logger. Add to your LightningModule and they arrive through the logger like any other metric:

from lightning.pytorch.utilities import grad_norm
def on_before_optimizer_step(self, optimizer):
    self.log_dict(grad_norm(self, norm_type=2))

• viz: a connected visdom.Visdom() instance
• env: environment name (default: viz.env if set, otherwise auto-generated from timestamp)

Note: log_metrics and log_hyperparams run on rank zero only. Use one logger instance per Trainer run. Not thread-safe — internal state has no locking.

Note: values that don't convert to a float (non-numeric strings, multi-element tensors, None) are skipped with a warning rather than raising.

See example/train_lightning_example.py for a full working example.

Requirements: pip install visdom scikit-learn

visdom.loggers.VisdomSklearnLogger patches all sklearn fit() calls so every estimator trained after autolog() logs to Visdom automatically — no per-estimator code needed.

GridSearchCV / RandomizedSearchCV produce a bar chart of mean_test_score per parameter combination and a text pane with best_score_, best_params_, and fit time.

Iterative estimators additionally get a line chart of their per-iteration training history: MLPClassifier/MLPRegressor plot loss_curve_ (plus validation_scores_ when fit with early_stopping=True), and GradientBoostingClassifier/GradientBoostingRegressor plot train_score_.

Regressors get train_rmse and train_mae rows in the text pane alongside the R2 train_score (R2 alone can be misleading), plus a predicted-vs-residual scatter plot.

Note: train_score, train_rmse, train_mae and the residual scatter are all measured on the data passed to fit(). They describe fit quality on the training set and are not held-out estimates — score your own test set for that.

Note: one logger is active at a time. Calling autolog() again switches the active env silently — no warning is raised, and the previous env stops receiving updates.

import visdom
from visdom.loggers import VisdomSklearnLogger
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import Ridge
from sklearn.model_selection import GridSearchCV
viz = visdom.Visdom()
VisdomSklearnLogger.autolog()
clf = RandomForestClassifier(n_estimators=100)
clf.fit(X_train, y_train)        # -> text pane
reg = Ridge(alpha=1.0)
reg.fit(X_train, y_train)        # -> text pane
gs = GridSearchCV(clf, param_grid, cv=3)
gs.fit(X_train, y_train)         # -> bar chart + text pane

import visdom
viz = visdom.Visdom(port=8098, server="http://myserver")
VisdomSklearnLogger.autolog(viz, env="sklearn_run")

• viz: a connected visdom.Visdom() instance (optional — created internally if not passed)
• env: environment name (default: viz.env if set, otherwise auto-generated from timestamp)

Requirements: pip install visdom xgboost

visdom.loggers.VisdomXGBLogger implements XGBoost's TrainingCallback protocol, plotting train/eval metrics to Visdom after every boosting round.

There was no way to visualize XGBoost training runs in Visdom without manually attaching a TrainingCallback and wiring up viz.line() calls yourself. This adds opt-in auto-logging behind a single autolog() call, with no changes required to model, train(), or fit() code.

import xgboost as xgb
import visdom
from visdom.loggers import VisdomXGBLogger
viz = visdom.Visdom()
VisdomXGBLogger.autolog(viz, env="xgb_run")
booster = xgb.train(params, dtrain, evals=[(dtrain, "train"), (dval, "eval")])  # logged automatically
clf = xgb.XGBClassifier().fit(X_train, y_train, eval_set=[(X_val, y_val)])      # logged automatically
xgb.cv(params, dtrain, nfold=3)                                                 # logged automatically

callback = VisdomXGBLogger(viz, env="xgb_run")
booster = xgb.train(params, dtrain, evals=[(dtrain, "train"), (dval, "eval")], callbacks=[callback])

Each eval metric gets its own window with one trace per data name (train/eval), and best_iteration/best_score are logged as a text pane once training finishes. See example/train_xgboost_example.py for a full working example.

Note: one logger is active at a time. Calling autolog() again for a different env moves logging there and warns; the previous env keeps the windows it already has. Import cross_validate after autolog() — importing it first binds the original function, and every fold then opens its own window instead of sharing one per metric.

Requirements: pip install visdom tensorflow (or pip install visdom keras)

visdom.loggers.VisdomKerasLogger implements Keras's Callback protocol, plotting train/val metrics to Visdom after every epoch.

from tensorflow import keras
from tensorflow.keras import layers
import visdom
from visdom.loggers import VisdomKerasLogger
viz = visdom.Visdom()
logger = VisdomKerasLogger(viz, env="keras_run")
model = keras.Sequential([
    layers.Input(shape=(20,)),
    layers.Dense(32, activation="relu"),
    layers.Dense(1, activation="sigmoid"),
])
model.compile(optimizer="adam", loss="binary_crossentropy", metrics=["accuracy"])
model.fit(
    x_train, y_train,
    validation_data=(x_val, y_val),
    epochs=20,
    callbacks=[logger],
)

A metric named val_ is plotted as a val trace on the same window its train counterpart plots as a train trace, matching how Keras already splits train/val by key prefix. One instance can be reused across multiple fit() calls — a new run's epoch 0 replaces the previous run's curve on the same windows in place, rather than opening a duplicate set of windows.

Per-batch logging with log_every — use when you also want step-level detail on large datasets. Off by default, since on_train_batch_end otherwise fires every batch regardless of whether step-level detail is wanted:

logger = VisdomKerasLogger(viz, env="keras_run", log_every=50)
model.fit(x_train, y_train, epochs=20, callbacks=[logger])

Each metric gets its own window titled " (step)", throttled to one send every log_every batches. The optimizer's current learning rate is read (not computed) and plotted alongside as lr.

Experiment tracking with params — records the run in the ExperimentStore alongside the charts, so it becomes queryable through vis.search_experiments / vis.compare_experiments. Off by default. Without params the logger only ever calls viz.line():

logger = VisdomKerasLogger(viz, env="keras_run", params={"lr": 0.01})
model.fit(x_train, y_train, epochs=20, callbacks=[logger])
viz.search_experiments("status = finished")

Hyper-parameters are recorded when training begins, each epoch's metrics as they are plotted, and the run is marked finished when fit() returns. Only epoch metrics are recorded — per-batch values from log_every stay visualization-only so a run's metric history keeps the granularity the search and compare views read it at.

Note: a finished experiment rejects further writes, so an env records one tracked run. Give every run its own env, including a repeat run of the same script. Keras reports no exception to on_train_end, so a tracked run is always recorded as finished. Call viz.finish_experiment(status="failed", env=...) directly to record a run that did not.

• viz: a connected visdom.Visdom() instance
• env: environment name (default: viz.env if set, otherwise auto-generated from timestamp)
• log_every: also plot metrics at batch granularity, one send every N batches (default: None, disabled)
• params: hyper-parameters to record, opting the run into experiment tracking (default: None, disabled)

Note: not thread-safe — internal state has no locking, so calling fit() on the same logger instance from multiple threads can race.

See example/train_keras_example.py for a full working example.

Requirements: pip install visdom optuna

Dashboard visualizations: pip install plotly

visdom.integrations.OptunaCallback implements Optuna's study callback protocol. After each trial finishes it records the trial's parameters, objective values and state as a Visdom experiment in a dedicated environment. Optuna is not a Visdom dependency, so existing Visdom users do not install it unless they choose this integration.

import optuna
import visdom
from visdom.integrations import OptunaCallback
viz = visdom.Visdom()
callback = OptunaCallback(
    viz,
    dashboard_env="optuna_quadratic",
    objective_names=["loss"],
    create_dashboard=True,
    refresh_every=10,
    contour_params=["x", "y"],
)
def objective(trial):
    x = trial.suggest_float("x", -10, 10)
    y = trial.suggest_float("y", -10, 10)
    return (x - 2)  2 + (y + 1)  2
study = optuna.create_study(study_name="quadratic", direction="minimize")
study.optimize(objective, n_trials=100, callbacks=[callback])
callback.update_dashboard(study)

callback = OptunaCallback(
    viz,
    dashboard_env="optuna_accuracy_latency",
    objective_names=["accuracy", "latency_ms"],
    create_dashboard=True,
)
def multi_objective(trial):
    width = trial.suggest_int("width", 1, 10)
    accuracy = 0.80 + 0.01 * width
    latency_ms = 10.0 + 2.0 * width
    return accuracy, latency_ms
study = optuna.create_study(
    study_name="accuracy-latency",
    directions=["maximize", "minimize"],
)
study.optimize(multi_objective, n_trials=40, callbacks=[callback])
callback.update_dashboard(study)

The integration records one experiment per trial, using names such as optuna_quadratic_trial_000017. Intermediate values reported with trial.report(value, step) are stored as the intermediate_value metric in step order before the final objective value. Each experiment also carries a stable optuna_dashboard_env tag. With create_dashboard=True, the first trial creates summary, HParams, optimization history and timeline panes, plus intermediate-value and parameter-importance panes when Optuna can compute them. Supplying at least two parameter names through contour_params adds a contour pane for each objective; Optuna handles numerical, categorical and log-scaled parameters when it builds those Plotly figures. The HParams pane selects experiments by that dashboard tag rather than by a callback-local list, so update_dashboard() on a new callback recovers trials logged before a process restart. Dashboard refreshes from one callback are serialized, so study.optimize(..., n_jobs=N) cannot publish them out of order. When multiple processes or nodes share a study and dashboard namespace, enable create_dashboard=True in exactly one process; callbacks in the other workers still log their trials with the default create_dashboard=False. The designated writer's tag query includes trials from every worker. After all workers finish, have the coordinating process call update_dashboard() once for the final refresh.

Completed studies with two or three objectives also get a Pareto-front pane. Later trials refresh the panes in optuna_quadratic every refresh_every successful writes by the dashboard writer. The explicit final update_dashboard() includes any trials left since the last scheduled refresh. Plotly is only needed for the Optuna visualization panes. Timeline bars preserve each trial's true duration, and a fixed-size marker at the true start time keeps even sub-pixel trials visible and hoverable without exaggerating their runtime.

Pass raise_on_error=True if a Visdom logging failure should stop optimization; by default it emits a warning and allows the study to continue. Single- and multi-objective studies are supported, and COMPLETE, PRUNED and FAIL states are preserved in the optuna_state tag. A pruned trial retains every intermediate value reported before pruning. Optuna remains responsible for the pruning decision: call trial.report() and trial.should_prune() inside the objective and raise optuna.TrialPruned when requested. Because Optuna invokes study callbacks after a trial reaches a terminal state, OptunaCallback records these values after the trial finishes rather than streaming them while the trial is running. Optuna does not support trial.report() or trial.should_prune() for multi-objective studies, so intermediate-value and pruning support applies only to single-objective studies.

Details

Basics

vis.image

This function draws an

# Convert HxWxC → CxHxW before passing to vis.image
img = img.transpose(2, 0, 1)   # NumPy
img = img.permute(2, 0, 1)     # PyTorch

The following opts are supported:

• jpgquality: JPG quality (number 0-100). If defined image will be saved as JPG to reduce file size. If not defined image will be saved as PNG.
• caption: Caption for the image
• store_history: Keep all images stored to the same window and attach a slider to the bottom that will let you select the image to view. You must always provide this opt when sending new images to an image with history.

Programmatically set the visible frame of an image_history pane from Python:

win = vis.image(img, opts=dict(store_history=True))
vis.image(img2, win=win, opts=dict(store_history=True))
vis.update_image_slider(win, index=1)  # show second frame

The index is 0-based and is clamped to the valid range by the server. NumPy integer scalars (e.g. np.int64) are accepted and coerced automatically. Passing a non-integer or a non-image_history window raises an error.

This function overlays a saliency or attention heatmap on top of an image. It takes a CxHxW or HxW array img (uint8 or float) and an HxW float array heatmap with values in [0, 1]. The blending is per-pixel — pixels where the heatmap is near zero stay close to the original image, so a zero-gradient background does not get tinted by the colormap.

import numpy as np
from visdom import Visdom
viz = Visdom()
img: CxHxW uint8 or float in [0, 1]
heatmap: HxW float in [0, 1] — e.g. from a saliency method or attention map
viz.image_heatmap(img, heatmap, opts=dict(title="Saliency", alpha=0.6, colormap="jet"))

Any attribution method that produces an HxW numpy array works — gradient saliency, GradCAM, SHAP, or a hand-computed attention map.

The following opts are supported:

• alpha: blend strength (float in [0, 1]; default = 0.5). Higher values make the heatmap more visible.
• colormap: matplotlib colormap name (string; default = 'jet'). Falls back to a blue-red gradient if matplotlib is not installed.
• caption: caption for the image pane
• jpgquality: JPG quality (number 0-100). If set, the result is encoded as JPEG. Otherwise PNG.
• normalize: normalize the image to [0, 1] before blending (boolean; default = False)

Note heatmap accepts any finite float range. Values outside [0, 1] are rescaled automatically via min-max normalization, so methods like SHAP or Integrated Gradients that return signed or unnormalized values work without any pre-processing. NaN maps to 0; infinite values are clamped to the [0, 1] boundary.

This function draws a list of images. It takes an input B x C x H x W tensor or a list of images all of the same size. It makes a grid of images of size (B / nrow, nrow).

The following arguments and opts are supported:

• nrow: Number of images in a row
• padding: Padding around the image, equal padding around all 4 sides
• opts.jpgquality: JPG quality (number 0-100). If defined image will be saved as JPG to reduce file size. If not defined image will be saved as PNG.
• opts.caption: Caption for the image

... (README truncated for length)