Run an HTTP server in Python
Serve a folder over HTTP with one command, and know where that command stops being enough.
Python ships with an HTTP server in the standard library. One command serves the current folder to your browser, with nothing to install.
The short answer
python -m http.server
Open http://localhost:8000 and you see the files in the folder you ran it from. If there is an index.html, that is served; otherwise you get a directory listing. Press Ctrl+C to stop it.
On some systems the command is python3, and on Windows py -m http.server works too.
Port, bind address and directory
The port is the one positional argument. The default is 8000:
python -m http.server 9000
By default the server listens on every network interface, so other devices on your network can reach it. That is handy for testing on a phone and unwelcome on cafe wifi. To make it a Python localhost server that only your own machine can reach, bind it to the loopback address:
python -m http.server 8000 --bind 127.0.0.1
To serve a folder other than the current one:
python -m http.server --directory build
The short forms are -b and -d.
Python simple HTTP server: the old name
If you searched for SimpleHTTPServer, that was the Python 2 module:
python -m SimpleHTTPServer 8000
Python 3 folded it into http.server, so on any current Python that command fails with "No module named SimpleHTTPServer". The replacement is python -m http.server 8000, and it behaves the same way.
Starting the server from code
The same server is available as a class, which is useful when you want to start it from a script or a test:
from functools import partial
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
handler = partial(SimpleHTTPRequestHandler, directory="build")
with ThreadingHTTPServer(("127.0.0.1", 8000), handler) as server:
print("Serving on http://127.0.0.1:8000")
server.serve_forever()
serve_forever blocks until the process is interrupted. ThreadingHTTPServer handles each request in its own thread, so one slow download does not hold up the next request.
Older answers build this from socketserver directly, and that still works:
import http.server
import socketserver
with socketserver.TCPServer(("", 8000), http.server.SimpleHTTPRequestHandler) as httpd:
httpd.serve_forever()
ThreadingHTTPServer is a socketserver.TCPServer underneath, with threading and sensible socket options already switched on, so prefer it.
A custom handler that returns JSON
To send something other than files, subclass BaseHTTPRequestHandler and write a do_GET method. This one returns JSON:
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class ApiHandler(BaseHTTPRequestHandler):
def do_GET(self):
if self.path == "/api/status":
self.send_json(200, {"status": "ok"})
else:
self.send_json(404, {"error": "not found"})
def send_json(self, code, payload):
body = json.dumps(payload).encode("utf-8")
self.send_response(code)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
The order matters: status line, headers, end_headers(), then the body as bytes. To try it without blocking, bind to port 0 so the OS picks a free port, run the server in a background thread and make a request:
import threading
import urllib.request
server = ThreadingHTTPServer(("127.0.0.1", 0), ApiHandler)
port = server.server_address[1]
threading.Thread(target=server.serve_forever, daemon=True).start()
with urllib.request.urlopen(f"http://127.0.0.1:{port}/api/status") as response:
print(response.status, response.read()) # 200 b'{"status": "ok"}'
server.shutdown()
server.server_close()
For a POST, add a do_POST method and read the body with self.rfile.read(int(self.headers["Content-Length"])).
Why it is not for production
The Python docs say it plainly: http.server is not recommended for production. It only implements basic security checks. In practice that means:
- No HTTPS unless you wrap the socket yourself.
- No protection against slow or malicious clients, and no request limits.
- No caching headers, compression or logging you would want on a live site.
- A directory listing of everything in the folder, including files you forgot were there.
It is a development tool. For a real application, use a framework behind a production server; the web server overview covers those. For static files, use a static host or nginx.
When the folder is a site you are building
http.server serves files exactly as they are on disk. That works for a folder of downloads. It gets tiresome when the folder is a website you are working on: you refresh by hand after every change, and /about is a 404 because the file is about.html.
If the site is built with Nitro CLI, its dev server handles both:
nitro dev
That builds the site, serves it at http://localhost:3000, rebuilds when a source file changes and reloads the browser for you. It also resolves clean URLs, so /about serves about.html the way most static hosts do. nitro dev --port 8080 changes the port, and --no-reload turns the reloading off.
To check the production build before deploying:
nitro build
nitro preview
nitro preview serves the finished build folder at http://localhost:4000 with no live reload, so you see what a host will serve.
This only helps if the site is a Nitro project. For sharing a folder or looking at some HTML files, python -m http.server is still the right tool.
Common questions
How do I stop the server? Ctrl+C in the terminal it is running in. If the port still reads as in use, another copy is running somewhere; find it with lsof -i :8000 on macOS or Linux.
Why do I get "Address already in use"? Something else is listening on that port. Pick another one, such as python -m http.server 8001, or stop the other process.
Can it serve over HTTPS? Not from the command line on most Python versions. You can wrap the server socket with the ssl module in a script, but for local HTTPS a tool such as mkcert with a proper dev server is less work.
Can other people on my network see it? Yes, unless you pass --bind 127.0.0.1. Anyone who can reach your machine on that port can browse the folder.
This page uses Nitro CLI.
Build static sites with Python code instead of template engines. Live reload, incremental builds, deploy anywhere.
$ pip install nitro-cli