Guides

Copyparty on a VPS: a self-hosted file server behind nginx with HTTPS

Set up copyparty, the self-hosted file server, on a VPS: accounts and volumes, systemd, nginx with HTTPS, WebDAV and SFTP, resumable uploads and security.

Published ~9 min read
On this page

Short answer: copyparty is a self-hosted file server in a single Python file: a web interface with resumable uploads, plus WebDAV, SFTP, FTP(S), TFTP and SMB if you switch them on. On a VPS, run copyparty-sfx.py as its own user with a config file, listen on 127.0.0.1 only, and put nginx with a Let's Encrypt certificate in front of it.

Debian · Ubuntu
sudo useradd -r -s /usr/sbin/nologin -m -d /var/lib/copyparty copyparty
sudo curl -fL -o /usr/local/bin/copyparty-sfx.py \
  https://github.com/9001/copyparty/releases/latest/download/copyparty-sfx.py
sudo mkdir -p /srv/files && sudo chown copyparty:copyparty /srv/files

This guide follows the copyparty README, its contrib/systemd and contrib/nginx files and the command-line help, as published for v1.20.26 (released 14 October 2026), read on 13 November 2026. We did not run copyparty for this article; nothing below is a benchmark or a test result of ours.

What copyparty is, and which file to run

copyparty is MIT-licensed and written in Python. The server needs nothing but Python; thumbnails, media indexing, SFTP and the other extras use optional packages. The README lists several ways to get it:

  • copyparty-sfx.py, the first option in the quickstart, the one the README marks as recommended and the one the project's systemd unit expects. It is a self-extractor: on start it unpacks an embedded archive into the temp directory. Download it only from the GitHub releases or the official mirror copyparty.eu; the README warns against SourceForge.
  • The pip package (python3 -m pip install --user -U copyparty in the README). On Debian 12 and Ubuntu 24.04 the system Python is marked as externally managed, so pip refuses to install into it; use the sfx there, or uv tool run copyparty, which the README also lists.
  • copyparty.exe for Windows, packages for Arch, Homebrew and NixOS (the README notes that a Fedora package does not exist yet), a Docker image, and a zipapp (copyparty.pyz) that avoids the extraction step at slightly lower performance.

For thumbnails of images, audio and video, the README's Debian line is sudo apt install --no-install-recommends python3-pil ffmpeg. Leave it out if you only store files.

Accounts, volumes and permissions

A volume maps a folder on disk to a URL path, and each volume lists who may do what. On the command line that is -a USER:PASS for an account and -v SRC:DST:PERM,USER for a volume: the README's example -v /mnt/music:/music:r:rw,foo -a foo:bar shares /mnt/music as /music, readable by anyone and writable by foo. For a server, a config file is easier to read and can be reloaded without a restart. The permission letters:

LetterAllows
rBrowse, download, download folders as zip or tar
wUpload, and move or copy files into the folder
mMove files and folders out of the folder
dDelete
gDownload a file by its exact URL, without seeing the listing
hLike g, but folders return their index.html
aAdmin: upload times, uploader IPs, config reload
AAll of the above: rwmda plus dotfiles

* means everyone, including visitors who are not logged in, and @acct means every account. Write-only folders (w alone) work: users can upload but not see what is there.

Set it up on a VPS behind nginx

  1. 1Write the config file
    /etc/copyparty.conf
    [global]
      i: 127.0.0.1          # listen on localhost only; nginx is the front door
      usernames             # require username AND password at login
      e2dsa                 # index all volumes (search, upload undo)
      xff-hdr: x-real-ip    # nginx passes the client IP in this header
      rproxy: 1             # and that header holds exactly one IP
      df: 4                 # refuse uploads when less than 4 GiB is free
    
    [accounts]
      alice: CHANGE-ME-long-random-password
      bob: CHANGE-ME-another-long-password
    
    [/]
      /srv/files
      accs:
        A: alice            # full control
        r: bob              # read and download only

    Comments need two spaces before the #. Without usernames, copyparty logs you in by password alone (the README: any username plus your password), so two accounts must never share a password. There is no * in the volume, so visitors without an account get nothing. Generate passwords with openssl rand -base64 24, and keep the file readable for root and the service only: sudo chown root:copyparty /etc/copyparty.conf and sudo chmod 640 /etc/copyparty.conf.

  2. 2Add the systemd unit

    The project ships contrib/systemd/copyparty.service with comments and extra hardening lines; copy that file. Its core is:

    /etc/systemd/system/copyparty.service (core lines)
    [Unit]
    Description=copyparty file server
    
    [Service]
    Type=notify
    SyslogIdentifier=copyparty
    Environment=PYTHONUNBUFFERED=x
    ExecReload=/bin/kill -s USR1 $MAINPID
    User=copyparty
    Group=copyparty
    WorkingDirectory=/var/lib/copyparty
    Environment=XDG_CONFIG_HOME=/var/lib/copyparty/.config
    ExecStart=/usr/bin/python3 /usr/local/bin/copyparty-sfx.py -c /etc/copyparty.conf
    
    [Install]
    WantedBy=multi-user.target
    bash
    sudo systemctl daemon-reload
    sudo systemctl enable --now copyparty
    journalctl -u copyparty -f          # watch it start

    The upstream file also grants CAP_NET_BIND_SERVICE so copyparty could listen on ports 80 and 443 itself; behind nginx you can drop that line. systemctl reload copyparty rereads the volumes and accounts, while changes in [global] need a restart. The systemd service guide explains each directive.

  3. 3Put nginx and HTTPS in front

    The README recommends a reverse proxy for HTTPS instead of copyparty's own TLS, and names nginx's config as the recommended example. Condensed from contrib/nginx/copyparty.conf:

    /etc/nginx/sites-available/files.example.com
    server {
        listen 80;
        server_name files.example.com;
    
        client_max_body_size 1024M;      # uploads arrive in chunks of up to 96 MiB
        client_header_timeout 610m;
        client_body_timeout 610m;
        send_timeout 610m;
    
        location / {
            proxy_pass http://127.0.0.1:3923;
            proxy_redirect off;
            proxy_http_version 1.1;
            proxy_buffering off;
            proxy_request_buffering off;
            proxy_set_header Connection        "Keep-Alive";
            proxy_set_header Host              $host;
            proxy_set_header X-Real-IP         $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        }
    }

    Enable the site, then let certbot add the certificate and the HTTPS redirect as in our nginx reverse proxy guide. copyparty's browser uploader sends files in chunks, by default aiming at 64 MiB and allowing up to 96 MiB per request. The project's nginx file notes that nginx's default limit of 1 MB blocks uploads larger than 256 MiB, and the README asks proxies for a limit of at least 96 MiB.

  4. 4Close everything else

    Port 3923 listens on localhost only, so the firewall needs just 80, 443 and SSH, as set up in the UFW guide. Open more ports only for protocols you actually enable.

Protocols: WebDAV, SFTP, FTP, TFTP and SMB

The README's feature list names HTTP(S), WebDAV, SFTP, FTP(S), TFTP and SMB/CIFS. Only the web interface and WebDAV are on by default; each of the others needs an option and its own port:

ProtocolEnable withREADME notes
HTTP and the web UIon (port 3923)Resumable up2k uploads; HTTPS via a reverse proxy
WebDAVon, same port as HTTPRead-write; mount as a drive in Windows, macOS, Linux; --no-dav turns it off
SFTP--sftp 3922Needs paramiko; SSH keys by default, --sftp-pw allows passwords
FTP / FTPS--ftp 3921, --ftps 3990Uploads not resumable; set a passive range with --ftp-pr
TFTP--tftp 3969No accounts at all; meant for old hardware
SMB/CIFS--smb (read-only), --smbwNeeds impacket; the README calls it unsafe, slow and not for WAN

Behind nginx, WebDAV works through the same HTTPS address, which makes it the easiest way to mount the share. SFTP, FTP and SMB bypass nginx and need their ports open. For a plain file drop that you reach with an SFTP client, the server's own OpenSSH is usually simpler; the file transfer guide and the SFTP vs FTPS comparison cover that route.

Uploads: up2k, resume and deduplication

Drag files or whole folders into the browser and the up2k uploader takes over. Per the README, it splits files into chunks and checksums each one, resumes after a dropped connection or even a reboot (upload the same files again), skips files the server already has, has no file size limit even behind a proxy that limits request size, and keeps the original modification time. Restarting or upgrading copyparty during an upload is safe. Uploads over FTP are the exception and cannot resume. For scripts there is a command-line uploader, u2c.py, in the repository's bin folder.

Security basics

  • No anonymous write. Give * at most r or g. If strangers must upload, use a write-only volume, the safety option -s, which disables thumbnails and the use of FFmpeg and Pillow, and the volume flag nohtml, which the README recommends against XSS: it returns uploaded HTML and SVG as plain text.
  • Strong, unique passwords, ideally hashed. With ah-alg: argon2 in [global] (needs argon2-cffi), copyparty prints hashed versions of plaintext passwords at start-up so you can replace them in the file.
  • Get the client IP right. Brute force protection bans an IP for 24 hours after more than 9 wrong passwords within an hour (the default), which only works when copyparty sees the real client address; that is what the xff-hdr and rproxy lines above are for. copyparty trusts that header only from 127.0.0.0/8 and ::1 by default, which fits nginx on the same server.
  • Stay current. Updating is replacing the sfx file and restarting the service. The README documents a vc-url option that checks the project's security advisories and warns admins on the control panel.
  • Isolate it further if you like: the repository includes prisonparty (a chroot) and bubbleparty (bubblewrap) wrappers.

On a VPS, the disk is the limit that matters: use df: 4 or a larger value so a big upload cannot fill the root filesystem, and keep the shared folder on a separate disk or volume if you have one. Check disk usage before you hand out accounts.

Frequently asked

What is copyparty?

copyparty is an MIT-licensed, self-hosted file server written in Python. It serves a web interface with resumable, checksummed uploads and can also speak WebDAV, SFTP, FTP(S), TFTP and SMB. The server needs only Python; thumbnails, SFTP and other extras use optional packages.

How do I run copyparty as a service on Linux?

Download copyparty-sfx.py to /usr/local/bin, create a system user, write /etc/copyparty.conf with accounts and volumes, and install the project's contrib/systemd/copyparty.service. Then run systemctl daemon-reload and systemctl enable --now copyparty, and follow the log with journalctl -u copyparty -f.

Is copyparty safe to expose to the internet?

Only with accounts: started without arguments it gives everyone read and write access to the current folder. Give anonymous users read access at most, use long unique passwords, bind it to 127.0.0.1 behind an HTTPS reverse proxy, and set xff-hdr and rproxy so its brute force bans hit the real client IP.

Should copyparty handle HTTPS itself?

The README recommends ignoring the built-in TLS and putting a reverse proxy such as nginx or Caddy in front, because proxies follow TLS best practices and copyparty does not speak HTTP/2 or QUIC. Raise nginx's client_max_body_size to at least 96 MiB so chunked uploads pass.

Related articles

All guides