Skip to main content

A simple HTTP server for handleing file uploads

Project description


ngus is a minimalist HTTP server written in pure Python and intended for receiving file uploads


The reason for writing this small package was the need to transfer files from a Windows desktop machine running on a highly restricted VPN to my GNU and UNIX systems.

Since the HTTP traffic (out) was not restricted, I started looking for a small , yet flexible HTTP server that could satisfy the following criteria:

  • can be configured with the help of a few CLI parameters

  • can be started and stopped quickly by an unprivileged user

  • be able to receive uploads to a specific directory

  • be portable and require a minimal amount of dependencies

  • be part of the C/C++ or Python ecosystems

To my amazement I wasn't able to find any free software matching that criteria.


The main purpose of ngus is to accept file uploads as POST requests from an HTTP client.

Currently ngus does not provide encryption (HTTPS) support. Many different tools can be employed to serve as an HTTPS proxy.

See the examples bellow for more details!


pip (pypi)

pip install ngus


layman -a sgs
emerge www-servers/ngus


When installing ngus as described above, a dedicated ngus script (entry point) will be installed in addition to the ngus Python module.


ngus -h

will be for all practical purposes the same as running:

python -m ngus -h

The latter format will be used for the rest of this section.

python -m ngus -H -p 8080

will start the server, binding port 8080 on all available interfaces and storing the received uploads in the current working directory (CWD), while

python -m ngus -H -p 8080 -u /home/s/uploads

will store them in /home/s/uploads

Note: This will allow ngus to replace any existing file in this directory.

Once the server is running a client will be able to send a POST form with a file data. One can always access the URL (send a GET request) with a regular browser and use the provided form or simply use a client like curl for posting (sending a POST request) a form.

curl -F ""

The default form input field name is ufile. That can be changed by using the --input-name parameter. Basic auth support can be added with the --basic-auth parameter.

python -m ngus -H -p 8080 -i uploadfile -b "uname:foo" -u /home/s/uploads
curl --basic -u uname -F ""

Using nginx as a proxy

ngus will usually not be run on ports 80 (HTTP) and 443 (HTTPS) since binding them requires administrator (root) privileges.

Running ngus on a unprivileged port (> 1024) may not solve the problem described above. Namely a potential client may not be able to communicate to ports other than 80 and 443 because of imposed firewall / VPN restrictions.

Another potential challenge arises when ngus runs on a host that is not publicly accessible.

nginx can be used to proxy the traffic toward ngus instance running as described in the examples above.

server {

   listen 443 ssl;
   listen 80;

   access_log /var/log/nginx/;
   error_log /var/log/nginx/ error;


   location / {
       # point at the ngus instance running on a private network address


... and then upload a file with:

curl -F ""

Support and contributing

ngus is hosted on GitHub:


Simeon Simeonov - sgs @ LiberaChat


Copyright (c) 2021, Simeon Simeonov All rights reserved.

Licensed under the GNU General Public License v3.0 or later. SPDX-License-Identifier: GPL-3.0-or-later

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ngus-1.0.tar.gz (29.3 kB view hashes)

Uploaded Source

Built Distribution

ngus-1.0-py3-none-any.whl (31.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page