Run a web server from any folder
By Flavio
Published · Updated
Tagged: Node.js
Learn how to spin up a quick local web server from any folder using http-server with Node.js, Python http.server, or PHP's built-in php -S command.
You can run a web server from any folder on your system with a single command. Node.js, Python and PHP all give you one, so whatever language you already have installed, you’re covered.
This is a common need. You have absolutely no time to configure a proper web server like Apache or Nginx, because this is just for a few minutes, or for testing your app.
Why not just double-click the HTML file and open it in the browser? Because pages loaded from file:// URLs run with restrictions. fetch() calls to local files fail, and ES modules won’t load. A local server serves everything over http://localhost, the way a real server would.
Let’s see the options, depending on the language you prefer.
Node.js
If you use Node.js and you have installed npm already, run
npm install -g http-server
and then run http-server in the folder you want to expose through your server.
By default it will start the server on port 8080, but you can change it using the -p flag (see more options by running http-server --help).
Alternatively, you can skip the global install and run it directly with npx:
npx http-server
npx downloads the package if needed and runs it, so nothing stays installed on your machine.
A few options I use often:
# serve another folder, on port 3000
npx http-server ./dist -p 3000
# turn off browser caching, so you always see your latest edits
npx http-server -c-1
# open the browser for you
npx http-server -o
The caching one matters more than it looks. By default http-server tells the browser to cache files for 3600 seconds (1 hour). You change a CSS file, reload, and nothing happens. -c-1 disables that.
Single page apps
If your app uses client-side routing (React Router, Vue Router), a URL like /about has no matching file on disk. A plain static server returns 404 when you reload that page.
http-server has two ways around it. It serves a 404.html file for any path it can’t find, so you can copy index.html to 404.html. Or you can use the catch-all trick from its docs, which sends every unknown path back to the index page:
npx http-server --proxy http://localhost:8080?
Note the ? at the end. Use the same port the server runs on.
Python
If you use Python and have it installed, just run
python3 -m http.server 8080
to start a local server on port 8080. Without the port number it uses 8000.
To serve a different folder without moving into it, use --directory (Python 3.7 and later):
python3 -m http.server 8080 --directory dist
``` Old tutorials show `python -m SimpleHTTPServer`, which is the Python 2 version. Python 2 reached end of life in 2020.
Most Linux distributions ship Python 3, so there it's often the zero-setup option. macOS doesn't include Python anymore: the first time you run `python3`, it offers to install Apple's Command Line Tools, which come with Python 3. You can also install it with [Homebrew](/homebrew/).
I go further with that module, including a custom handler, routing, and POST bodies, in [Python, create a Web (HTTP) server](/python-http-server/).
## PHP
If you use PHP and you run a modern version of it, run
```bash
php -S localhost:8080
This is the built-in development server. It’s meant for testing, not production, but for a quick local check it’s all you need.
It serves the current folder. Use -t to pick another one as the document root:
php -S localhost:8080 -t public
If you request a folder, it looks for index.php or index.html in it.
You can also pass a PHP file as a “router” script. PHP runs it on every request. If it returns false, the server sends the requested file as it is. Otherwise, whatever the script prints is the response. This is how you add a single page app fallback:
<?php
// router.php
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
if (file_exists(__DIR__ . '/public' . $path)) {
return false;
}
readfile(__DIR__ . '/public/index.html');
php -S localhost:8080 -t public router.php
The server runs a single process, so one slow request blocks the others. Fine for local work, and another reason not to put it online.
Open it from your phone
Sometimes you want to test the page on your phone, or show it to someone on the same Wi-Fi.
http-server and Python listen on all network interfaces by default. Find your computer’s local IP address, then open http://<that IP>:8080 on the phone. On a Mac, this usually prints it (en0 is the Wi-Fi interface on most Macs, if it prints nothing try en1):
ipconfig getifaddr en0
PHP only listens on the address you give it. localhost means only your computer can reach it. Use 0.0.0.0 to make it reachable from the network:
php -S 0.0.0.0:8080
The flip side: when you’re on a coffee shop or office network, other people on it can reach the Node and Python servers too, and browse every file in that folder. Bind to localhost when you don’t need that:
npx http-server -a 127.0.0.1
python3 -m http.server 8080 --bind 127.0.0.1
If the port is already taken
One error you’ll hit sooner or later: you start a server and get something like EADDRINUSE (Node) or Address already in use (Python).
It means another process is already listening on that port, probably a server you started earlier and forgot about. Pick a different port, like 8081, or find and stop the old process.
On macOS and Linux, lsof tells you which process holds the port:
lsof -i :8080
The second column is the process ID. Stop it with kill, using that number:
kill 12345
On Linux, ports below 1024 require root, so stick with high numbers like 8080.
Want me to talk about your product? You can sponsor this site.
Related posts about node: