Improve local development setup instructions in README

README.md

@@ -179,6 +179,24 @@ Install from source
 > pip install git+https://github.com/fossasia/visdom
 ```
 
+## Local Development Setup (From Scratch)
+
+### 1. Create environment
+,,,bash
+conda create -n visdom_env python=3.10 -y
+conda activate visdom_env
+pip install -r requirements.txt
+pip install pillow charset-normalizer
+pip install -e .
+python example/demo.py
+
+### Troubleshooting
+
+If you are running directly from source without installing the package:
+
+PYTHONPATH=./py python -m visdom.server
+,,,bash
+
 ## Usage
 
 Start the server (probably in a  `screen` or `tmux`) from the command line:
@@ -800,3 +818,4 @@ See guidelines for contributing [here.](./CONTRIBUTING.md)
 
 ## Acknowledgments
 Visdom was inspired by tools like [display](https://github.com/szym/display) and relies on [Plotly](https://plot.ly/) as a plotting front-end.
+

py/visdom/server/run_server.py

@@ -49,21 +49,33 @@ def start_server(
         use_frontend_client_polling=use_frontend_client_polling,
         eager_data_loading=eager_data_loading,
     )
-    if bind_local:
-        app.listen(port, max_buffer_size=1024**3, address="127.0.0.1")
-    else:
-        app.listen(port, max_buffer_size=1024**3)
-    logging.info("Application Started")
-    logging.info(f"Working directory: {os.path.abspath(env_path)}")
 
+    import sys
+
+    try:
+        if bind_local:
+            app.listen(port, max_buffer_size=1024**3, address="127.0.0.1")
+        else:
+            app.listen(port, max_buffer_size=1024**3)
+
+        logging.info("Application Started")
+        logging.info(f"Working directory: {os.path.abspath(env_path)}")
+
+    except OSError:
+        print(f"\nError: Port {port} is already in use.")
+        print("Try running on another port:")
+        print(f"python -m visdom.server -port {port+1}\n")
+        sys.exit(1)
+
+    # KEEP ORIGINAL CODE BELOW (IMPORTANT)
     if "HOSTNAME" in os.environ and hostname == DEFAULT_HOSTNAME:
         hostname = os.environ["HOSTNAME"]
-    else:
-        hostname = hostname
+
     if print_func is None:
         print("You can navigate to http://%s:%s%s" % (hostname, port, base_url))
     else:
         print_func(port)
+
     ioloop.IOLoop.instance().start()
     app.subs = []
     app.sources = []