Contributing to Visdom
We want to make contributing to this project as easy and transparent as possible.
Before you post an issue on our tracker, please check the following list of issues to see if it resolves your issue. If this document does not resolve your problem, please scroll all the way down for details on how to report an issue.
In all your interactions with us, please keep in mind that visdom is a side project that we work on in our spare time. We are happy to help, but there are no engineers dedicated to visdom so we cannot accommodate all your requests and questions right away.
Issue: I cannot connect to the visdom server.
First, check that your visdom server is running. You can start the visdom server
python -m visdom.server. Try restarting the server.
If your visdom server is running, but you don't see anything when trying to
access visdom in your browser, please check that your network settings don't
block traffic between the visdom server and your browser. Traffic may be blocked
by a firewall, or you may need to specify a proxy server when starting the
visdom server (via the
-proxy option). In some cases, it may help to set up an
SSH tunnel to your server by adding the following line to your local
LocalForward 127.0.0.1:8097 127.0.0.1:8097
It's also possible that the port is being blocked by your firewall, and some users have reported that the
sudo ufw allow 8097 command helps them.
Issue: I see a blue screen in my browser, but I do not see visualizations.
unfortunately, a common issue for users in China. In Chrome, click
the dependencies manually:
/home/$USERNAME/$ANACONDA_FOLDER/lib/python$PYTHON_VERSION/site-packages/visdom-$VISDOM_VERSION-py$PYTHON_VERSION.egg. Note that the variables
$VISDOM_VERSIONmay not be set and depend on your configuration. Furthermore, if you are installing from source or using another method of installing dependancies, the folder to use may be different.
download.shscript and either execute it to automatically download the resources or manually download all the files that it requests.
Issue: I would like to make a plot that has feature X: To produce visualizations, visdom uses plot.ly. Specifically, the client code produces a JSON-structure that is passed on to plot.ly by the server. This implies that, given the right input, visdom can display any visualization that plot.ly supports. You can find an up-to-date guide to plot.ly features here.
The visdom exposes easy access to the most common plot.ly features, but does not
expose all of them. You are more than welcome to hack the client code producing
the data structure (in
py/__init__.py) to include the feature you want to use.
All available options for each plot type are described in the plot.ly manual.
You can even construct your own plot data structure from scratch, and
it to the visdom server directly.
If you believe a feature is so generally useful that it should be exposed directly in the visdom client, please send us a pull request; we will happily accept them!
Issue: I want to use a recently added visdom feature that is not in the pip version: You can always install visdom from source. Clone the Github repo (and make your own code changes, if any). In the visdom source folder, run:
pip uninstall visdom && pip install -e .
For some pip installs, this approach does not always properly link the visdom
module. In that case, try running
python setup.py install instead.
How to report an issue:
If you identified a bug, please include the following information in your bug report:
- The error message produced by the visdom server (if any). Copy-paste this error message from your Terminal.
- The platform that you're running on (OS, browser, visdom version).
This information will help us to more rapidly identify the source of your issue.
We actively welcome your pull requests.
- Fork the repo and create your branch from
- If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Ensure the Lua and Python interfaces to Visdom are in sync.
- If you change
js/, commit the React-compiled version of
main.js. For details, please see
Contributing to the UIbelow.
- Add demos for new features. Ensure the demos work.
- Make sure your code lints.
- If you haven't already, complete the Contributor License Agreement ("CLA").
Contributing to the UI
The UI is built with React. This means that
js/ needs to be compiled. This can be done with
To clarify an inconsistency, Panes in the UI are the containers for the
'windows' referred to by the Python and Lua APIs.
You can find instructions for install
cd /path/to/visdom yarn # install node dependencies yarn run build # build js
You can find instructions for installing
cd /path/to/visdom npm install # install node dependencies npm run build # build js
Contributor License Agreement ("CLA")
In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Facebook's open source projects.
Complete your CLA here: https://code.facebook.com/cla
We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.
Facebook has a bounty program for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue.
- 3 spaces for indentation rather than tabs for Lua
- Follow PEP 8 for Python
- 80 character line length
By contributing to Visdom, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.