Editing your website with a local python http server!

>Windows: Press the windows key + R to open the run dialogue (or search "run" in the start menu). Then type "cmd" and hit enter. You can also use windows powershell if you prefer, which you should be able to find if you type powershell in the search bar of your start menu. You might need to run it as administrator if you bump into permissions issues, just be careful executing code as admin. These steps won't break your system, but not all code plays nice! :)

>macOS: My knowledge of macOS is pretty limited (I only run OS9 at home for retro stuff and it's been a while since I've used a mac for work, so ymmv! Let me know if this doesn't work for you and I'll update it!) Press command (the ⌘ key) and space to open spotlight, then type "terminal" and hit enter. Alternatively, in the finder window for your website's files, press command + option (⌥) + T and it should open a new terminal window already in the right directory.

>Linux: I'm going to assume if you've made it as far as installing a linux distro, you at least *kind* of know what you're doing. The linux side of this tutorial is mostly for people who are beginners to both web design and who aren't super familiar with their distro yet. Most distros let you open the terminal with control + T. Some file viewers will also let you open a terminal by right clicking in the directory you want to open it in.

1. Find your local IP address
   Note: this isn't the same as your public ip! It's the ip address that your wifi router assigns to your device locally. It usually starts with 192.168. and yo can find it in a few different ways. If you have access to your wifi router's admin panel, you can look through the list of connected devices and find it there. Otherwise, do some fiddlin' in the terminal to get the right one:
   Linux/macOS:
   

   ip a

   or

   ifconfig

   
   Look for something like

   192.168.x.x

   or

   10.0.x.x

   
   
   Windows:
   

   ipconfig

   
   Look for

   IPv4 Address

2. Run the Python server bound to all interfaces
   python -m http.server 8000 --bind 0.0.0.0
   This allows other devices on your network to connect to the server.
3. Visit the local IP address with the correct port from your other devices
   Normally you could go to "http://localhost:8000" on the computer you're running the web server script on and it would load the files no problem, but if you're on another device you need to point it through your network to the right place.
   In your browser, go to:
   http://your-ip-address:8000
   
   Example:
   http://192.168.1.42:8000
4. (optional, but maybe necessary depending on your setup) allow Python through your firewall
   If your computer (or your network as a whole) has strong firewall protections enabled by default, you might need to give Python permission to serve the webserver across your whole network. Note: this only work to share the server on your private network, it won't expose anything to the internet unless you set up port forwarding or tunneling which is a whoooole other thing so dw about it!
   
   Linux (UFW):
   sudo ufw allow 8000
   This opens port 8000 for incoming traffic. If you're using a different port, replace 8000 with the one you're using.
   
   Linux (iptables):
   sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
   If you don't know what iptables is then you probably don't need to use it, this is for more advanced setups and I'm only including it just in case!
   
   Windows:
   When you first run the Python server, a firewall prompt might appear. Make sure to allow Python on Private networks (e.g. your home Wi-Fi). If you accidentally clicked "No", you can search for "Allow an app through Windows Firewall" and manually enable it later.
   
   macOS:
   Go to System Settings → Network → Firewall → Options and ensure Python (or Terminal, if you're running it from there) is allowed incoming connections.
   If no prompt appears and things aren’t loading on other devices, try turning the firewall off temporarily just to test, or use:
   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /path/to/python3
   Then:
   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /path/to/python3
   (replace with your actual Python binary path if needed)
   
   Just a heads up about permissions:
   You might need to run some of these commands as administrator (Windows/macOS) or with sudo on Linux.
   If that's the case and you don't feel confident making changes with admin privileges, I'd advise that you don't until you're more familiar with your own system and network in case something breaks. Also, burying the lead here a little bit, but if you’re on a school or managed network you most likely won't be able to open ports without admin rights. If that's the case you should contact your IT department for help/advice before trying to make any kind of network-wide changes. :3

Save often, keep backups, don't assume everything will survive a crash.

If you can, set your work to autosave every so often. Consider learning how to use git so you can upload and save different versions of your project. Have backups that exist elsewhere too, like in a google drive or dropbox. You won't need it until you do.

When writing your code, the best practice is to use relative paths for everything that you link.

This means that you shouldn't hardcode your links to their absolute path unless they're already hosted externally. If you're adding files that aren't already live on the internet, then you're not going to be able to see them as you make changes, resulting in a lot of broken code or outdated versions, and it'll save you a lot of headaches in the long run if you start off as you mean to continue.

For example:

I want to link to an image. I plan to host it myself, no hotlinking, so it'll exist in my websites own files. In my backup folder that we made from the zip extract, from where we're serving the python html server, I put it inside another folder called images. When I upload it to the neocities server, I can use the absolute path to link to it from anywhere on my site or elsewhere on the web, but until it's actually uploaded (and I'm connected to the internet) that link won't work for local testing. 

The relative path, however, will work with the local server even if I haven't already uploaded anything, even if I lose connection, even if neocities servers go down, and it will slot seamlessly into my website once everything is actually live.

The local path for me on my computer for this example would be /home/aspen/projects/webdev/example/images/image.png

The absolute path, once I've uploaded all of my files to neocities, would be: https://example.neocities.org/ioages/image.png

And the relative path, the one I want to use in my code: /images/image.png

Relative paths can get a bit confusing once you're nested a few folders deep, though. Everything with a / in front of it means that it's the path from root- the base url of your website, and when you're working locally, the directory you launched the server from.

eg: https://example.neocities.org/ is my website's root, and /home/aspen/projects/webdev/example/ is my offline version's root

But let's say I'm building Dipper's webpage, which is located inside a folder at /dipper/index.html, and I want to use files from /images/ in my root, but I also have a bunch of dip pics inside /dipper/images/ that are neatly organised away from the rest of my misc. files so that I can keep an eye on how many photos of him specifically I have.

But! I also want to link to a file that's over in /worlds/simpsons/ because, idk, maybe there's a picture of a dog there that kind of looks like him, and it doesn't make a lot of sense to reupload it to his directory just to link it once.

In that case, I have a few options for how I link with relative paths, and I need to mix and match based on where the file is saved.

../ before the file name tells the server "go back one folder, then look for this file"

/ before the file name means "look for this starting from root"

and nothing before the file name (eg. just image.png) means "look for it starting from this folder".

That also means any folders that exist inside this folder are included in this search too, you just need to point to them first without adding any dots or slashes
(eg images/image.png)

Basically, the relative path needs to be updated to be correct for the page you're working on, and keeping track of that can be a little confusing at first, but it gets way easier especially if you have dedicated folders for your files. You can reuse the same files this way without needing to have multiple copies of them, including js/css/html!

To close your server, press control + C in your terminal window and it will exit.

It'll also disappear if you close your terminal window or restart your computer. Your files are still there even if you close this, and all you need to do to if you want to restart it is run the command again.

Sometimes, locally cached versions of your files might persist, so if you hit refresh and your changes don't seem to be appearing, you should try a hard refresh.

Here's how you do that in different browsers:

Chrome (and other Chromium based browsers like Opera and Brave), Firefox, Microsoft Edge
Windows/Linux: Ctrl + F5 or Shift + F5 or Ctrl + Shift + R
Mac: Command + Shift + R

----------------------

Safari
Mac: Command + Option + R 
(apparently safari doesn't hard refresh the same way as other browsers? but this should reload without using the cache)

Try out some custom scripts if you want automatic updates/https support/extra features.

Yeah, you'll need to refresh as you go with the basic web server. It can be a bit annoying, so if you want to have everything sync automatically the way it does on a site like codepen, you're going to need to dive a little deeper into python scripts.

There's plenty of different options out there, written by people who know what they're actually doing, and I encourage you to have a little browse on github to see what other folk have come up with and figure out what works for you- But here's what I'm using for me, cobbled together with my limited knowledge and some AI assistance. (Btw- that means you can take it and use it for whatever you want- any scripts I write with AI help I share as open source, because I can't claim ownership of something generated by something that was trained on other people's work. I don't know how to write python from scratch yet, but still need to make some custom tools, so this is the compromise!)

 #!/usr/bin/env python3

# === AUTO-INSTALL DEPENDENCIES ===
import sys
import subprocess
import shutil

DEBUG = "--debug" in sys.argv  # detect early

# === CHECK FOR PIP FIRST ===
if DEBUG:
    print("[🔍] Checking for pip...")

pip_path = shutil.which("pip") or shutil.which("pip3")

if not pip_path:
    print("\n[🚫] pip is not installed on this system.")
    print("    Please install pip before running this script.")
    print("    Try: sudo apt install python3-pip\n")
    sys.exit(1)

if DEBUG:
    try:
        version_output = subprocess.check_output([pip_path, "--version"], text=True).strip()
        print(f"[ℹ️] {version_output}")
    except Exception as e:
        print(f"[⚠️] Failed to get pip version: {e}")

REQUIRED_PACKAGES = ["watchdog", "websockets"]

for pkg in REQUIRED_PACKAGES:
    if DEBUG:
        print(f"[🔍] Checking for package: {pkg}")
    try:
        __import__(pkg)
        if DEBUG:
            print(f"[✅] {pkg} is already installed")
    except ImportError:
        print(f"[❌] Missing '{pkg}', installing...")
        subprocess.check_call([sys.executable, "-m", "pip", "install", pkg])
        print(f"[✅] Installed '{pkg}' successfully")

# === REAL IMPORTS ===
import http.server
import socketserver
import threading
import asyncio
import websockets
import os
import time
import argparse
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

# === CONFIG ===
PORT = 8000
WS_PORT = 5678
WATCH_PATH = "."

clients = set()

RELOAD_EXTENSIONS = {
    ".html", ".htm",
    ".css",
    ".js", ".mjs",
    ".json",
    ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp",
    ".woff", ".woff2", ".ttf", ".otf",
    ".ico"
}

INJECT_SCRIPT = """

"""

# === CUSTOM HTTP HANDLER ===
class InjectingRequestHandler(http.server.SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header("Access-Control-Allow-Origin", "*")
        super().end_headers()

    def do_GET(self):
        path = self.translate_path(self.path)
        if os.path.isdir(path):
            path = os.path.join(path, "index.html")

        if path.endswith(".html") and os.path.isfile(path):
            try:
                with open(path, "r", encoding="utf-8") as f:
                    content = f.read()

                if "" in content:
                    content = content.replace("", INJECT_SCRIPT + "\n")
                else:
                    content += INJECT_SCRIPT

                encoded = content.encode("utf-8")
                self.send_response(200)
                self.send_header("Content-type", "text/html; charset=utf-8")
                self.send_header("Content-Length", str(len(encoded)))
                self.end_headers()
                self.wfile.write(encoded)
                return

            except Exception as e:
                self.send_error(500, f"Injection error: {e}")
                return

        return super().do_GET()

# === REUSABLE TCP SERVER (avoids zombie port errors) ===
class ReusableTCPServer(socketserver.TCPServer):
    allow_reuse_address = True

def create_http_server():
    print(f"[📂] Serving files from: {os.getcwd()}")
    return ReusableTCPServer(("", PORT), InjectingRequestHandler)

# === BROADCAST TO CLIENTS ===
async def broadcast_reload():
    if clients:
        print("[🔁] Reloading live view")
        await asyncio.gather(*[client.send("reload") for client in clients])

async def websocket_handler(websocket, path):
    clients.add(websocket)
    try:
        await websocket.wait_closed()
    finally:
        clients.remove(websocket)

# === WATCHDOG HANDLER ===
class ReloadHandler(FileSystemEventHandler):
    def __init__(self, loop, debug=False):
        self.loop = loop
        self.debug = debug
        self.last_reload_time = 0
        self.debounce_seconds = 0.2

    def on_any_event(self, event):
        if event.is_directory:
            if self.debug:
                print(f"[📁] Directory event ignored: {event.src_path}")
            return

        filepath = event.src_path
        ext = os.path.splitext(filepath)[1].lower()

        if ext in RELOAD_EXTENSIONS:
            now = time.time()
            if now - self.last_reload_time < self.debounce_seconds:
                return
            self.last_reload_time = now

            if event.event_type == "created":
                if self.debug:
                    print(f"[🆕] New file detected: {filepath}")
                else:
                    print(f"[🆕] New file: {os.path.basename(filepath)} → reload")
            elif event.event_type == "modified":
                if self.debug:
                    print(f"[🔁] Detected changes to: {filepath}")
                else:
                    print(f"[🔁] Changed: {os.path.basename(filepath)} → reload")

            asyncio.run_coroutine_threadsafe(broadcast_reload(), self.loop)
        else:
            if self.debug:
                print(f"[📄] Ignored change: {filepath}")

# === MAIN ENTRYPOINT ===
def main():
    global DEBUG

    parser = argparse.ArgumentParser(description="🕸 Live-reloading web server")
    parser.add_argument("--debug", action="store_true", help="Show debug output for all file events")
    args = parser.parse_args()
    DEBUG = args.debug

    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)

    httpd = create_http_server()

    def run_http():
        with httpd:
            print(f"[🌐] Serving HTTP on http://localhost:{PORT}")
            httpd.serve_forever()

    http_thread = threading.Thread(target=run_http)
    http_thread.start()

    ws_server_obj = loop.run_until_complete(
        websockets.serve(websocket_handler, "localhost", WS_PORT)
    )

    observer = Observer()
    observer.schedule(ReloadHandler(loop, debug=DEBUG), WATCH_PATH, recursive=True)
    observer.start()

    print("[👀] Watching for changes in current directory...")
    if DEBUG:
        print("[🐞] Debug mode enabled: all file events will be printed")

    try:
        loop.run_forever()
    except KeyboardInterrupt:
        print("\n[👋] Shutting down... please wait.")
        try:
            observer.stop()
            observer.join()

            for ws in list(clients):
                loop.run_until_complete(ws.close())

            ws_server_obj.close()
            loop.run_until_complete(ws_server_obj.wait_closed())

            httpd.shutdown()
            httpd.server_close()

            http_thread.join()

            loop.stop()
            loop.close()

            print("[✅] All services stopped cleanly")

        except Exception as e:
            print(f"[💥] Error during shutdown: {e}")
            sys.exit(1)

if __name__ == "__main__":
    main()
  

Open up your favourite text editor, paste that bad boy in, and save it as something like "webserver.py". Linux users, make sure you make it executable by doing chmod +x webserver.py in the terminal, or through the right click context menu in your file manager.

There's two ways I can use this script in my day to day use:

• Drop it straight into my working directory, and launch it from the terminal from inside that directory with python3 webserver.py - this is probably easiest for anyone not running linux to just use it straight out of the box.
• put it in my ~/bin/ directory, then create an alias in my .bashrc file, like this:
Copy

cp webserver.py ~/bin/webserver.py
chmod +x ~/bin/webserver.py
echo "alias webserver='python3 ~/bin/webserver.py'" >> ~/.bashrc
source ~/.bashrc
        

Now whenever I navigate to a directory in my terminal that I want to launch as a web server, I just type webserver and it launches the script.

It uses watchdog to track the files that are changed in real time, and websockets to keep it all refreshed by injecting some javascript into the headers of the pages served by the webserver without editing the files themselves. These are extra dependencies that need to be installed separately from python, using pip. The script should check for this before it starts.
You can also run it in debug mode by adding the --debug flag at the end, which tells more about what it's scanning and what it's doing in the terminal as it goes. It gets a lil spammy so it's off by default. To shut it down, just like the basic webserver, press control + C in your terminal. It should at least attempt to release the port it's serving on. :3