[opensourcedex]

copyparty is a free, open source file management & sync project written in Python and released under MIT. It has 47,235 GitHub stars, 1,918 forks and 252 open issues, and was last pushed 13 days ago. On this registry it ranks #4 of 83 tracked projects in File Management & Sync, with 5 head-to-head comparisons available. It gained 382 stars over the last 30 tracked days.

What is copyparty?

copyparty is a portable file server that turns almost any device into a file server with resumable uploads and downloads through any web browser, built for self-hosters, homelab operators, NAS owners and anyone who wants to share files directly from their own hardware.

What it is

copyparty is a single-file Python program that serves files over HTTP(S), WebDAV, SFTP, FTP(S), TFTP and SMB/CIFS. It lives in the self-hosted file-sharing and NAS-frontend corner of the Python ecosystem, and it stands in for the stack of separate daemons people would otherwise run side by side: a WebDAV server, an FTP daemon, a TFTP daemon and a separate web frontend for uploads. Everything ships as one script, copyparty-sfx.py, so a working server is a single file and a Python interpreter rather than a set of installed services.

The concrete problem it solves is moving files between devices that do not share a client. A browser is the only client required, and uploads and downloads resume after a dropped connection. The server itself needs only Python 2 or 3, with all dependencies optional, which means it runs on hardware as small as a router or a NAS where installing packages is inconvenient. On top of transport, it handles the parts of file transfer that usually need extra tooling: deduplication on upload, thumbnails and a media index, per-folder and per-user permissions, temporary share links, and feeds for RSS readers and e-book readers. The project has 46,729 stars and 1,905 forks on GitHub, which indicates wide self-hosted adoption rather than a niche experiment.

Key capabilities

  • One process speaks HTTP(S), WebDAV, SFTP, FTP(S), TFTP and SMB/CIFS, so phones, file managers and scripts can all reach the same storage over their native protocol.
  • Browser interface includes a grid view toggled with g or 田, keyboard hotkeys, a navpane or breadcrumb switcher, thumbnails, a media player, an audio equalizer and a dynamic range compressor.
  • Uploads are resumable, deduplicated, and support "race the beam" playback of a file while it is still uploading, with an ETA for incoming files shown in the control panel.
  • Upload control covers unpost for undoing and deleting accidental uploads, self-destruct lifetimes on uploads, and shares that expose a file or folder through a temporary link.
  • File-search lets a user drop files into the browser to check whether they already exist on the server, and folders or selections download as zip or tar archives.
  • Accounts and volumes give per-folder, per-user permissions, with shadowing to hide subfolders and Unix-style dotfile handling.
  • Integration output includes RSS feeds, OPDS feeds for e-book readers, m3u8 playlists, and a recent-uploads listing.

Who uses it and how

  • Homelab and NAS owners use it as a frontend that makes existing storage reachable from a browser without adding services to the machine.
  • Server operators run it where moving files must not require extra packages, since only Python 2 or 3 is needed and every dependency is optional.
  • Mobile users upload and download through the Android app or iPhone shortcuts rather than a desktop client.
  • People who need to hand files to others use temporary shares and self-destruct uploads instead of leaving content permanently exposed.
  • Public read-only mirrors are viable: the project points to a read-only demo server running on a nuc in a basement.

Getting started

Download copyparty-sfx.py from the latest release at https://github.com/9001/copyparty/releases/latest/download/copyparty-sfx.py and run it. That is the whole install; the read-only demo server at https://a.ocv.me/pub/demo/ shows the result.

How it compares

The facts provide no list of paid products that copyparty replaces, so it stands alone in this registry as a single-file, multi-protocol file server. For readers who want a broader contrast, the README points to docs/versus.md, which holds the project's own comparison to similar software.

When to use it — and when not to

The operational load is low compared with most file servers, because no database, object store or SMTP service is required and the entire runtime is one Python file with optional dependencies. It is a poor fit for anyone who wants a vendor-managed hosted service with a support contract, since copyparty is MIT-licensed software you run yourself. Be aware that the README maintains a bugs section roughly sorted by chance of encounter, a "not my bugs" section, and breaking-change notes for upgrades, and the repository carries 252 open issues, so self-hosters should read the upgrade notes before moving between versions.

project readme (upstream, from github) — read inline

💾🎉 copyparty

turn almost any device into a file server with resumable uploads/downloads using any web browser

👉 Get started! or visit the read-only demo server 👀 running on a nuc in my basement

📷 screenshots: browser // upload // unpost // thumbnails // search // fsearch // zip-DL // md-viewer

🎬 videos: upload // cli-upload // race-the-beam // 👉 feature-showcase (youtube)

built in Norway 🇳🇴 with contributions from not-norway

readme toc

quickstart

just run copyparty-sfx.py -- that's it! 🎉

ℹ️ the sfx is a self-extractor which unpacks an embedded tar.gz into $TEMP -- if this looks too scary, you can use the zipapp which has slightly worse performance

enable thumbnails (images/audio/video), media indexing, and audio transcoding by installing some recommended deps:

  • Alpine: apk add py3-pillow ffmpeg
  • Debian: apt install --no-install-recommends python3-pil ffmpeg
  • Fedora: rpmfusion + dnf install python3-pillow ffmpeg --allowerasing
  • FreeBSD: pkg install py311-sqlite3 py311-pillow ffmpeg
  • MacOS: port install py-Pillow ffmpeg
  • MacOS (alternative): brew install pillow ffmpeg
  • Windows: python -m pip install --user -U Pillow
    • install python and ffmpeg manually; do not use winget or Microsoft Store (it breaks $PATH)
    • copyparty.exe comes with Pillow and only needs ffmpeg for mediatags/videothumbs
  • see optional dependencies to enable even more features

running copyparty without arguments (for example doubleclicking it on Windows) will give everyone read/write access to the current folder; you may want accounts and volumes

or see some usage examples for inspiration, or the complete windows example

some recommended options:

  • -e2dsa enables general file indexing
  • -e2ts enables audio metadata indexing (needs either FFprobe or Mutagen)
  • -v /mnt/music:/music:r:rw,foo -a foo:bar shares /mnt/music as /music, readable by anyone, and read-write for user foo, password bar

mirrors

other places to download copyparty from (non-github links):

DO NOT download from sourceforge

at home

make it accessible over the internet by starting a cloudflare quicktunnel like so:

first download cloudflared and then start the tunnel with cloudflared tunnel --url http://127.0.0.1:3923

as the tunnel starts, it will show a URL which you can share to let anyone browse your stash or upload files to you

but if you have a domain, then you probably want to skip the random autogenerated URL and instead make a permanent cloudflare tunnel

since people will be connecting through cloudflare, run copyparty with --xff-hdr cf-connecting-ip to detect client IPs correctly

on servers

you may also want these, especially on servers:

because the following environment variables are commonly used in service-scripts, they are understood by copyparty:

and remember to open the ports you want; here's a complete example including every feature copyparty has to offer:

firewall-cmd --permanent --add-port={80,443,3921,3922,3923,3945,3990}/tcp  # --zone=libvirt
firewall-cmd --permanent --add-port=12000-12099/tcp  # --zone=libvirt
firewall-cmd --permanent --add-port={69,1900,3969,5353}/udp  # --zone=libvirt
firewall-cmd --reload

(69:tftp, 1900:ssdp, 3921:ftp, 3922:sftp, 3923:http/https, 3945:smb, 3969:tftp, 3990:ftps, 5353:mdns, 12000:passive-ftp)

features

also see comparison to similar software

  • backend stuff
  • upload
    • ☑ basic: plain multipart, ie6 support
    • ☑ up2k: js, resumable, multithreaded
      • no filesize limit! even on Cloudflare
    • ☑ stash: simple PUT filedropper
    • ☑ filename randomizer
    • ☑ write-only folders
    • ☑ unpost: undo/delete accidental uploads
    • ☑ self-destruct (specified server-side or client-side)
    • ☑ race the beam (almost like peer-to-peer)
    • ☑ symlink/discard duplicates (content-matching)
  • download
  • browser
    • ☑ navpane (directory tree sidebar)
    • ☑ file manager (cut/paste, delete, batch-rename)
    • ☑ audio player (with OS media controls and opus/mp3 transcoding)
      • ☑ play video files as audio (converted on server)
      • ☑ create and play m3u8 playlists
    • ☑ image gallery with webm player
      • ☑ and cbz manga/comics reader
    • ☑ textfile browser with syntax highlighting
      • ☑ realtime streaming of growing files (logfiles and such)
    • ☑ thumbnails
      • ☑ ...of images using Pillow, pyvips, or FFmpeg
      • ☑ ...of RAW images using libraw-dcraw_emu or rawpy
      • ☑ ...of videos using FFmpeg
      • ☑ ...of audio (spectrograms) using FFmpeg
      • ☑ cache eviction (max-age; maybe max-size eventually)
    • ☑ multilingual UI (english, norwegian, chinese, add your own))
    • ☑ SPA (browse while uploading)
  • server indexing
  • client support
  • markdown

PS: something missing? post any crazy ideas you've got as a feature request or discussion 🤙

testimonials

small collection of user feedback

good enough, surprisingly correct, certified good software, just works, why, wow this is better than nextcloud

  • UI просто ужасно. Если буду описывать детально не смогу удержаться в рамках приличий

motivations

project goals / philosophy

  • inverse unix philosophy -- do all the things, and do an okay job
    • quick drop-in service to get a lot of features in a pinch
    • some of the alternatives might be a better fit for you
  • run anywhere, support everything
    • as many web-browsers and python versions as possible
      • every browser should at least be able to browse, download, upload files
      • be a good emergency solution for transferring stuff between ancient boxes
    • minimal dependencies
      • but optional dependencies adding bonus-features are ok
      • everything being plaintext makes it possible to proofread for malicious code
    • no preparations / setup necessary, just run the sfx (which is also plaintext)
  • adaptable, malleable, hackable
    • no build steps; modify the js/python without needing node.js or anything like that

becoming rich is specifically not a motivation, but if you wanna donate then see my github profile regarding donations for my FOSS stuff in general (also THANKS!)

notes

general notes:

  • paper-printing is affected by dark/light-mode! use lightmode for color, darkmode for grayscale
    • because no browsers currently implement the media-query to do this properly orz

browser-specific:

  • iPhone/iPad: use Firefox to download files
  • Android-Chrome: increase "parallel uploads" for higher speed (android bug)
  • Android-Firefox: takes a while to select files (their fix for ☝️)
  • Desktop-Firefox: may use gigabytes of RAM if your files are massive seems to be OK now
  • Desktop-Firefox: may stop you from unplugging USB flashdrives until you visit about:memory and click Minimize memory usage

server-os-specific:

  • RHEL8 / Rocky8: you can run copyparty using /usr/libexec/platform-python

server notes:

  • pypy is supported but regular cpython is faster if you enable the database

bugs

roughly sorted by chance of encounter

  • general:

    • --th-ff-jpg may fix video thumbnails on some FFmpeg versions (macos, some linux)
    • --th-ff-swr may fix audio thumbnails on some FFmpeg versions
    • if the up2k.db (filesystem index) is on a samba-share or network disk, you'll get unpredictable behavior if the share is disconnected for a bit
      • use --hist or the hist volflag (-v [...]:c,hist=/tmp/foo) to place the db and thumbnails on a local disk instead
      • or, if you only want to move the db (and not the thumbnails), then use --dbpath or the dbpath volflag
    • all volumes must exist / be available on startup; up2k (mtp especially) gets funky otherwise
    • probably more, pls let me know

  • python 3.4 and older (including 2.7):

  • python 2.7 on Windows:

    • cannot index non-ascii filenames with -e2d
    • cannot handle filenames with mojibake

if you have a new exciting bug to share, see reporting bugs

not my bugs

same order here too

  • Chrome issue 1317069 -- if you try to upload a folder which contains symlinks by dragging it into the browser, the symlinked files will not get uploaded

  • Chrome issue 1352210 -- plaintext http may be faster at filehashing than https (but also extremely CPU-intensive)

  • Chrome issue 383568268 -- filereaders in webworkers can OOM / crash the browser-tab

    • copyparty has a workaround which seems to work well enough

  • Firefox issue 1790500 -- entire browser can crash after uploading ~4000 small files

  • Windows: Uploading from a webbrowser may fail with "directory iterator got stuck" due to the max path length; try moving the files somewhere shorter before uploading

  • Android: music playback randomly stops due to battery usage settings

  • iPhones: the volume control doesn't work because apple doesn't want it to

    • AudioContext will probably never be a viable workaround as apple introduces new issues faster than they fix current ones

  • iPhones: music volume goes on a rollercoaster during song changes

    • nothing I can do about it because AudioContext is still broken in safari

  • iPhones: the preload feature (in the media-player-options tab) can cause a tiny audio glitch 20sec before the end of each song, but disabling it may cause worse iOS bugs to appear instead

    • just a hunch, but disabling preloading may cause playback to stop entirely, or possibly mess with bluetooth speakers
    • tried to add a tooltip regarding this but looks like apple broke my tooltips

  • iPhones: preloaded awo files make safari log MEDIA_ERR_NETWORK errors as playback starts, but the song plays just fine so eh whatever

    • awo, opus-weba, is apple's new take on opus support, replacing opus-caf which was technically limited to cbr opus

  • iPhones: preloading another awo file may cause playback to stop

    • can be somewhat mitigated with mp.au.play() in mp.onpreload but that can hit a race condition in safari that starts playing the same audio object twice in parallel...

  • Windows: folders cannot be accessed if the name ends with .

    • python or windows bug

  • Windows: msys2-python 3.8.6 occasionally throws RuntimeError: release unlocked lock when leaving a scoped mutex in up2k

    • this is an msys2 bug, the regular windows edition of python is fine

  • VirtualBox: sqlite throws Disk I/O Error when running in a VM and the up2k database is in a vboxsf

    • use --hist or the hist volflag (-v [...]:c,hist=/tmp/foo) to place the db and thumbnails inside the vm instead
      • or, if you only want to move the db (and not the thumbnails), then use --dbpath or the dbpath volflag
    • also happens on mergerfs, so put the db elsewhere

  • Ubuntu: dragging files from certain folders into firefox or chrome is impossible

    • due to snap security policies -- see snap connections firefox for the allowlist, removable-media permits all of /mnt and /media apparently

breaking changes

upgrade notes

  • 1.9.16 (2023-11-04):
    • --stats/prometheus: cpp_bans renamed to cpp_active_bans, and that + cpp_uptime are gauges
  • 1.6.0 (2023-01-29):
    • http-api: delete/move is now POST instead of GET
    • everything other than GET and HEAD must pass cors validation
  • 1.5.0 (2022-12-03): new chunksize formula for files larger than 128 GiB
    • users: upgrade to the latest cli uploader if you use that
    • devs: update third-party up2k clients (if those even exist)

FAQ

"frequently" asked questions

  • CopyParty?

    • nope! the name is either copyparty (all-lowercase) or Copyparty -- it's one word after all :>

  • what is a volflag?

    • per-volume configuration; many (not all) global-options can be set as volflags, and most (not all) volflags can be set as global-options; complete list of volflags

  • what is a volume?

    • a mapping from a URL (/music/) to a folder on your server's local filesystem (C:\Users\ed\Music) which can then be accessed through copyparty, depending on the permissions and options you set on it -- see accounts and volumes

  • can I change the 🌲 spinning pine-tree loading animation?

  • is it possible to block read-access to folders unless you know the exact URL for a particular file inside?

    • yes, using the g permission, see the examples there
    • you can also do this with linux filesystem permissions; chmod 111 music will make it possible to access files and folders inside the music folder but not list the immediate contents -- also works with other software, not just copyparty

  • can I link someone to a password-protected volume/file by including the password in the URL?

    • yes, by adding ?pw=hunter2 to the end; replace ? with & if there are parameters in the URL already, meaning it contains a ? near the end
      • if you have enabled --usernames then do ?pw=username:password instead
      • ?pw can be disabled with --pw-urlp=A but this breaks support for many clients

  • how do I stop .hist folders from appearing everywhere on my HDD?

    • by default, a .hist folder is created inside each volume for the filesystem index, thumbnails, audio transcodes, and markdown document history. Use the --hist global-option or the hist volflag to move it somewhere else; see database location

  • can I make copyparty download a file to my server if I give it a URL?

  • firefox refuses to connect over https, saying "Secure Connection Failed" or "SEC_ERROR_BAD_SIGNATURE", but the usual button to "Accept the Risk and Continue" is not shown

    • firefox has corrupted its certstore; fix this by exiting firefox, then find and delete the file named cert9.db somewhere in your firefox profile folder

  • the server keeps saying thank you for playing when I try to access the website

    • you've gotten banned for malicious traffic! if this happens by mistake, and you're running a reverse-proxy and/or something like cloudflare, see real-ip on how to fix this

  • copyparty seems to think I am using http, even though the URL is https

    • your reverse-proxy is not sending the X-Forwarded-Proto: https header; this could be because your reverse-proxy itself is confused. Ensure that none of the intermediates (such as cloudflare) are terminating https before the traffic hits your entrypoint

  • thumbnails are broken (you get a colorful square which says the filetype instead)

    • you need to install FFmpeg or Pillow; see thumbnails

  • thumbnails are broken, specifically for photos and videos taken by iphones

  • thumbnails are broken (some images appear, but other files just get a blank box, and/or the broken-image placeholder)

    • probably due to a reverse-proxy messing with the request URLs and stripping the query parameters (?th=w), so check your URL rewrite rules
    • could also be due to incorrect caching settings in reverse-proxies and/or CDNs, so make sure that nothing is set to ignore the query string
    • could also be due to misbehaving privacy-related browser extensions, so try to disable those

  • i want to learn python and/or programming and am considering looking at the copyparty source code in that occasion

    •  _|  _      __   _  _|_
(_| (_)     | | (_)  |_

accounts and volumes

per-folder, per-user permissions - if your setup is getting complex, consider making a config file instead of using arguments

  • much easier to manage, and you can modify the config at runtime with systemctl reload copyparty or more conveniently using the [reload cfg] button in the control-panel (if the user has a/admin in any volume)
    • changes to the [global] config section requires a restart to take effect
  • when using config-files, ignore all the -a and -v stuff below, and CTRL-F config file example on this page instead

a quick summary can be seen using --help-accounts

configuring accounts/volumes with arguments:

  • -a usr:pwd adds account usr with password pwd
  • -v .::r adds current-folder . as the webroot, readable by anyone
    • the syntax is -v src:dst:perm:perm:... so local-path, url-path, and one or more permissions to set
    • granting the same permissions to multiple accounts:
      -v .::r,usr1,usr2:rw,usr3,usr4 = usr1/2 read-only, 3/4 read-write

permissions:

  • r (read): browse folder contents, download files, download as zip/tar, see filekeys/dirkeys
  • w (write): upload files, move/copy files into this folder
  • m (move): move files/folders from this folder
  • d (delete): delete files/folders
  • . (dots): user can ask to show dotfiles in directory listings
  • g (get): only download files, cannot see folder contents or zip/tar
  • G (upget): same as g except uploaders get to see their own filekeys (see fk in examples below)
  • h (html): same as g except folders return their index.html, and filekeys are not necessary for index.html
  • a (admin): can see upload time, uploader IPs, config-reload
  • A ("all"): same as rwmda. (read/write/move/delete/admin/dotfiles)

examples:

  • add accounts named u1, u2, u3 with passwords p1, p2, p3: -a u1:p1 -a u2:p2 -a u3:p3
  • make folder /srv the root of the filesystem, read-only by anyone: -v /srv::r
  • make folder /mnt/music available at /music, read-only for u1 and u2, read-write for u3: -v /mnt/music:music:r,u1,u2:rw,u3
    • unauthorized users accessing the webroot can see that the music folder exists, but cannot open it
  • make folder /mnt/incoming available at /inc, write-only for u1, read-move for u2: -v /mnt/incoming:inc:w,u1:rm,u2
    • unauthorized users accessing the webroot can see that the inc folder exists, but cannot open it
    • u1 can open the inc folder, but cannot see the contents, only upload new files to it
    • u2 can browse it and move files from /inc into any folder where u2 has write-access
  • make folder /mnt/ss available at /i, read-write for u1, get-only for everyone else, and enable filekeys: -v /mnt/ss:i:rw,u1:g:c,fk=4
    • c,fk=4 sets the fk (filekey) volflag to 4, meaning each file gets a 4-character accesskey
    • u1 can upload files, browse the folder, and see the generated filekeys
    • other users cannot browse the folder, but can access the files if they have the full file URL with the filekey
    • replacing the g permission with wg would let anonymous users upload files, but not see the required filekey to access it
    • replacing the g permission with wG would let anonymous users upload files, receiving a working direct link in return

if you want to grant access to all users who are logged in, the group acct will always contain all known users, so for example -v /mnt/music:music:r,@acct

  • to do the opposite, granting access to everyone who is NOT logged in. *,-@acct does the trick, for example -v /srv/welcome:welcome:r,*,-@acct
  • single users can also be subtracted from a group: @admins,-james

anyone trying to bruteforce a password gets banned according to --ban-pw; default is 24h ban for 9 failed attempts in 1 hour

and if you want to use config files instead of commandline args (good!) then here's the same examples as a configfile; save it as foobar.conf and use it like this: python copyparty-sfx.py -c foobar.conf

  • you can also PRTY_CONFIG=foobar.conf python copyparty-sfx.py (convenient in docker etc)

config file example:

[accounts]
  u1: p1  # create account "u1" with password "p1"
  u2: p2  #  (note that comments must have
  u3: p3  #   two spaces before the # sign)

[groups]
  g1: u1, u2  # create a group

[/]     # this URL will be mapped to...
  /srv  # ...this folder on the server filesystem
  accs:
    r: *  # read-only for everyone, no account necessary

[/music]       # create another volume at this URL,
  /mnt/music   # which is mapped to this folder
  accs:
    r: u1, u2  # only these accounts can read,
    r: @g1     # (exactly the same, just with a group instead)
    r: @acct   # (alternatively, ALL users who are logged in)
    rw: u3     # and only u3 can read-write

[/inc]
  /mnt/incoming
  accs:
    w: u1   # u1 can upload but not see/download any files,
    rm: u2  # u2 can browse + move files out of this volume

[/i]
  /mnt/ss
  accs:
    rw: u1  # u1 can read-write,
    g: *    # everyone can access files if they know the URL
  flags:
    fk: 4   # each file URL will have a 4-character password

shadowing

hiding specific subfolders by mounting another volume on top of them

for example -v /mnt::r -v /var/empty:web/certs: (note: no permissions) mounts the server folder /mnt as the webroot, but another volume is mounted at /web/certs -- so visitors can only see the contents of /mnt and /mnt/web (at URLs / and /web), but not /mnt/web/certs because URL /web/certs is mapped to /var/empty

to fully unmap it from the filesystem, specify //NULL instead of a real path such as /var/empty, so for example -v /mnt::r -v //NULL:web/certs: ensures /web/certs will never be accessible by anyone

the example config file right above this section may explain this better; the first volume / is mapped to /srv which means http://127.0.0.1:3923/music would try to read /srv/music on the server filesystem, but since there's another volume at /music mapped to /mnt/music then it'll go to /mnt/music instead

so, to shadow a file/folder, define a volume but leave out the accs: section

ℹ️ this also works for single files, because files can also be volumes

config file example for unmapping folders by shadowing:

[/drives]
  /mnt   # url "/drives" goes to "/mnt"
  accs:
    r: *  # everyone can read

[/drives/foo/bar]
  //NULL  # blocks access to "/mnt/foo/bar"

dotfiles

unix-style hidden files/folders by starting the name with a dot

anyone can access these if they know the name, but they normally don't appear in directory listings

a client can request to see dotfiles in directory listings if global option -ed is specified, or the volume has volflag dots, or the user has permission .

for shares, the dots volflag is ignored

dotfiles do not appear in search results unless one of the above is true, and the global option / volflag dotsrch is set

even if user has permission to see dotfiles, they are default-hidden unless --see-dots is set, and/or user has enabled the dotfiles option in the settings tab

config file example, where the same permission to see dotfiles is given in two different ways just for reference:

[/foo]
  /srv/foo
  accs:
    r.: ed   # user "ed" has read-access + dot-access in this volume;
             # dotfiles are visible in listings, but not in searches
  flags:
    dotsrch  # dotfiles will now appear in search results too
    dots     # another way to let everyone see dotfiles in this vol

the browser

accessing a copyparty server using a web-browser

copyparty-browser-fs8

tabs

the main tabs in the ui

  • [🔎] search by size, date, path/name, mp3-tags ...
  • [🧯] unpost: undo/delete accidental uploads
  • [🚀] and [🎈] are the uploaders
  • [📂] mkdir: create directories
  • [📝] new-file: create a new textfile
  • [📟] send-msg: either to server-log or into textfiles if --urlform save
  • [🎺] audio-player config options
  • [⚙️] general client config options

hotkeys

the browser has the following hotkeys (always qwerty)

  • ? show hotkeys help
  • B toggle breadcrumbs / navpane
  • I/K prev/next folder
  • M parent folder (or unexpand current)
  • V toggle folders / textfiles in the navpane
  • G toggle list / grid view -- same as 田 bottom-right
  • T toggle thumbnails / icons
  • ESC close various things
  • ctrl-K delete selected files/folders
  • ctrl-X cut selected files/folders
  • ctrl-C copy selected files/folders to clipboard
  • ctrl-V paste (move/copy)
  • Y download selected files
  • F2 rename selected file/folder
  • when a file/folder is selected (in not-grid-view):
    • Up/Down move cursor
    • shift+Up/Down select and move cursor
    • ctrl+Up/Down move cursor and scroll viewport
    • Space toggle file selection
    • Ctrl-A toggle select all
  • when a textfile is open:
    • I/K prev/next textfile
    • S toggle selection of open file
    • M close textfile
  • when playing audio:
    • J/L prev/next song
    • U/O skip 10sec back/forward
    • 0..9 jump to 0%..90%
    • P play/pause (also starts playing the folder)
    • Y download file
  • when viewing images / playing videos:
    • J/L, Left/Right prev/next file
    • Home/End first/last file
    • F toggle fullscreen
    • S toggle selection
    • R rotate clockwise (shift=ccw)
    • Y download file
    • Esc close viewer
    • videos:
      • U/O skip 10sec back/forward
      • 0..9 jump to 0%..90%
      • P/K/Space play/pause
      • M mute
      • C continue playing next video
      • V loop entire file
      • [ loop range (start)
      • ] loop range (end)
  • when the navpane is open:
    • A/D adjust tree width
  • in the grid view:
    • S toggle multiselect
    • shift+A/D zoom
  • in the markdown editor:
    • ^s save
    • ^h header
    • ^k autoformat table
    • ^u jump to next unicode character
    • ^e toggle editor / preview
    • ^up, ^down jump paragraphs

navpane

switching between breadcrumbs or navpane

click the 🌲 or pressing the B hotkey to toggle between breadcrumbs path (default), or a navpane (tree-browser sidebar thing)

  • [+] and [-] (or hotkeys A/D) adjust the size
  • [🎯] jumps to the currently open folder
  • [📃] toggles between showing folders and textfiles
  • [📌] shows the name of all parent folders in a docked panel
  • [a] toggles automatic widening as you go deeper
  • [↵] toggles wordwrap
  • [👀] show full name on hover (if wordwrap is off)

thumbnails

press g or 田 to toggle grid-view instead of the file listing and t toggles icons / thumbnails

  • can be made default globally with --grid or per-volume with volflag grid
  • enable by adding ?imgs to a link, or disable with ?imgs=0

copyparty-thumbs-fs8

it does static images with Pillow / pyvips / FFmpeg, and uses FFmpeg for video files, so you may want to --no-thumb or maybe just --no-vthumb depending on how dangerous your users are

  • Pillow is 3x faster (and safer) than FFmpeg
  • disable thumbnails for specific volumes with volflag dthumb for all, or dvthumb / dathumb / dithumb for video/audio/images only
  • for installing FFmpeg on windows, see optional dependencies

audio files are converted into spectrograms using FFmpeg unless you --no-athumb (and some FFmpeg builds may need --th-ff-swr)

images with the following names (see --th-covers) become the thumbnail of the folder they're in: folder.png, folder.jpg, cover.png, cover.jpg

  • the order is significant, so if both cover.png and folder.jpg exist in a folder, it will pick the first matching --th-covers entry (folder.jpg)
  • and, if you enable file indexing, it will also try those names as dotfiles (.folder.jpg and so), and then fallback on the first picture in the folder (if it has any pictures at all)
  • disable folderthumbs with --th-covers no

enabling multiselect lets you click files to select them, and then shift-click another file for range-select

  • multiselect is mostly intended for phones/tablets, but the sel option in the [⚙️] settings tab is better suited for desktop use, allowing selection by CTRL-clicking and range-selection with SHIFT-click, all without affecting regular clicking
    • the sel option can be made default globally with --gsel or per-volume with volflag gsel

to show /icons/exe.png and /icons/elf.gif as the thumbnail for all .exe and .elf files respectively, do this: --ext-th=exe=/icons/exe.png --ext-th=elf=/icons/elf.gif

  • optionally as separate volflags for each mapping; see config file example below
  • the supported image formats are jpg, png, gif, webp, ico
    • be careful with svg; chrome will crash if you have too many unique svg files showing on the same page (the limit is 250 or so) -- showing the same handful of svg files thousands of times is ok however

note:

  • heif/heifs/heic/heics images usually require the libvips optional dependency but this is not possible with the docker-images due to legal reasons
  • if you do not want thumbnails to be generated on-the-fly, and instead wish to generate all of them on server startup, then see thumbnail pregen

config file example:

[global]
  no-thumb   # disable ALL thumbnails and audio transcoding
  no-vthumb  # only disable video thumbnails

[/music]
  /mnt/nas/music
  accs:
    r: *     # everyone can read
  flags:
    dthumb   # disable ALL thumbnails and audio transcoding
    dvthumb  # only disable video thumbnails
    ext-th:  exe=/ico/exe.png  # /ico/exe.png is the thumbnail of *.exe
    ext-th:  elf=/ico/elf.gif  # ...and /ico/elf.gif is used for *.elf
    th-covers:  folder.png,folder.jpg,cover.png,cover.jpg  # the default

zip downloads

download folders (or file selections) as zip or tar files

select which type of archive you want in the [⚙️] config tab:

name url-suffix description
tar ?tar plain gnutar, works great with curl | tar -xv
pax ?tar=pax pax-format tar, futureproof, not as fast
tgz ?tar=gz gzip compressed gnu-tar (slow), for curl | tar -xvz
txz ?tar=xz gnu-tar with xz / lzma compression (v.slow)
zip ?zip works everywhere, glitchy filenames on win7 and older
zip_dos ?zip=dos traditional cp437 (no unicode) to fix glitchy filenames
zip_crc ?zip=crc cp437 with crc32 computed early for truly ancient software
  • gzip default level is 3 (0=fast, 9=best), change with ?tar=gz:9
  • xz default level is 1 (0=fast, 9=best), change with ?tar=xz:9
  • bz2 default level is 2 (1=fast, 9=best), change with ?tar=bz2:9
  • hidden files (dotfiles) are excluded unless account is allowed to list them
    • up2k.db and dir.txt is always excluded
  • bsdtar supports streaming unzipping: curl foo?zip | bsdtar -xv
    • good, because copyparty's zip is faster than tar on small files
      • but ?tar is better for large files, especially if the total exceeds 4 GiB
  • zip_crc will take longer to download since the server has to read each file twice
    • this is only to support MS-DOS PKZIP v2.04g (october 1993) and older
      • how are you accessing copyparty actually

you can also zip a selection of files or folders by clicking them in the browser, that brings up a selection editor and zip button in the bottom right

copyparty-zipsel-fs8

cool trick: download a folder by appending url-params ?tar&opus or ?tar&mp3 to transcode all audio files (except aac|m4a|mp3|ogg|opus|wma) to opus/mp3 before they're added to the archive

  • super useful if you're 5 minutes away from takeoff and realize you don't have any music on your phone but your server only has flac files and downloading those will burn through all your data + there wouldn't be enough time anyways
  • and url-param &name=foo changes the name of the toplevel folder in the archive to foo, and just &name removes the folder entirely
  • and url-param &nodot skips dotfiles/dotfolders; they are included by default if your account has permission to see them
  • and url-params &j / &w produce jpeg/webm thumbnails/spectrograms instead of the original audio/video/images (&p for audio waveforms)
    • can also be used to pregenerate thumbnails; combine with --th-maxage=9999999 or --th-clean=0

uploading

drag files/folders into the web-browser to upload

dragdrop is the recommended way, but you may also:

when uploading files through dragdrop or CTRL-V, this initiates an upload using up2k; there are two browser-based uploaders available:

  • [🎈] bup, the basic uploader, supports almost every browser since netscape 4.0
  • [🚀] up2k, the good / fancy one

NB: you can undo/delete your own uploads with [🧯] unpost (and this is also where you abort unfinished uploads, but you have to refresh the page first)

up2k has several advantages:

  • you can drop folders into the browser (files are added recursively)
  • files are processed in chunks, and each chunk is checksummed
    • uploads autoresume if they are interrupted by network issues
    • uploads resume if you reboot your browser or pc, just upload the same files again
    • server detects any corruption; the client reuploads affected chunks
    • the client doesn't upload anything that already exists on the server
    • no filesize limit, even when a proxy limits the request size (for example Cloudflare)
  • much higher speeds than ftp/scp/tarpipe on some internet connections (mainly american ones) thanks to parallel connections
  • the last-modified timestamp of the file is preserved

it is perfectly safe to restart / upgrade copyparty while someone is uploading to it!
all known up2k clients will resume just fine 💪

see up2k for details on how it works, or watch a demo video

copyparty-upload-fs8

protip: you can avoid scaring away users with contrib/plugins/minimal-up2k.js which makes it look much simpler

protip: if you enable favicon in the [⚙️] settings tab (by typing something into the textbox), the icon in the browser tab will indicate upload progress -- also, the [🔔] and/or [🔊] switches enable visible and/or audible notifications on upload completion

the up2k UI is the epitome of polished intuitive experiences:

  • "parallel uploads" specifies how many chunks to upload at the same time
  • [🏃] analysis of other files should continue while one is uploading
  • [🥔] shows a simpler UI for faster uploads from slow devices
  • [🛡️] decides when to overwrite existing files on the server
    • 🛡️ = never (generate a new filename instead)
    • 🕒 = overwrite if the server-file is older
    • ♻️ = always overwrite if the files are different
  • [🎲] generate random filenames during upload
  • [🔎] switch between upload and file-search mode
    • ignore [🔎] if you add files by dragging them into the browser

and then there's the tabs below it,

  • [ok] is the files which completed successfully
  • [ng] is the ones that failed / got rejected (already exists, ...)
  • [done] shows a combined list of [ok] and [ng], chronological order
  • [busy] files which are currently hashing, pending-upload, or uploading
    • plus up to 3 entries each from [done] and [que] for context
  • [que] is all the files that are still queued

note that since up2k has to read each file twice, [🎈] bup can theoretically be up to 2x faster in some extreme cases (files bigger than your ram, combined with an internet connection faster than the read-speed of your HDD, or if you're uploading from a cuo2duo)

if you are resuming a massive upload and want to skip hashing the files which already finished, you can enable turbo in the [⚙️] config tab, but please read the tooltip on that button

if the server is behind a proxy which imposes a request-size limit, you can configure up2k to sneak below the limit with server-option --u2sz

if you want to replace existing files on the server with new uploads by default, run with --u2ow 2 (only works if users have the delete-permission, and can still be disabled with 🛡️ in the UI)

file-search

dropping files into the browser also lets you see if they exist on the server

copyparty-fsearch-fs8

when you drag/drop files into the browser, you will see two dropzones: Upload and Search

on a phone? toggle the [🔎] switch green before tapping the big yellow Search button to select your files

the files will be hashed on the client-side, and each hash is sent to the server, which checks if that file exists somewhere

files go into [ok] if they exist (and you get a link to where it is), otherwise they land in [ng]

  • the main reason filesearch is combined with the uploader is cause the code was too spaghetti to separate it out somewhere else, this is no longer the case but now i've warmed up to the idea too much

if you have a "wark" (file-identifier/checksum) then you can also search for that in the [🔎] tab by putting w = kFpDiztbZc8Z1Lzi in the raw field

unpost

undo/delete accidental uploads using the [🧯] tab in the UI

copyparty-unpost-fs8

you can unpost even if you don't have regular move/delete access, however only for files uploaded within the past --unpost seconds (default 12 hours) and the server must be running with -e2d

config file example:

[global]
  e2d            # enable up2k database (remember uploads)
  unpost: 43200  # 12 hours (default)

self-destruct

uploads can be given a lifetime, after which they expire / self-destruct

the feature must be enabled per-volume with the lifetime upload rule which sets the upper limit for how long a file gets to stay on the server

clients can specify a shorter expiration time using the up2k ui -- the relevant options become visible upon navigating into a folder with lifetimes enabled -- or by using the life upload modifier

specifying a custom expiration time client-side will affect the timespan in which unposts are permitted, so keep an eye on the estimates in the up2k ui

race the beam

download files while they're still uploading (demo video) -- it's almost like peer-to-peer

requires the file to be uploaded using up2k (which is the default drag-and-drop uploader), alternatively the command-line program

incoming files

the control-panel shows the ETA for all incoming files , but only for files being uploaded into volumes where you have read-access

copyparty-cpanel-upload-eta-or8

file manager

cut/paste, rename, and delete files/folders (if you have permission)

file selection: click somewhere on the line (not the link itself), then:

  • space to toggle

  • up/down to move

  • shift-up/down to move-and-select

  • ctrl-shift-up/down to also scroll

  • shift-click another line for range-select

  • cut: select some files and ctrl-x

  • copy: select some files and ctrl-c

  • paste: ctrl-v in another folder

  • rename: F2

you can copy/move files across browser tabs (cut/copy in one tab, paste in another)

shares

share a file or folder by creating a temporary link

when enabled in the server settings (--shr), click the bottom-right share button to share the folder you're currently in, or alternatively:

  • select a folder first to share that folder

Frequently asked questions

Is copyparty free to use?

copyparty is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does copyparty do?

Portable file server with accelerated resumable uploads, dedup, WebDAV, SFTP, FTP, TFTP, zeroconf, media indexer, thumbnails++ all in one file

What is copyparty written in?

copyparty is primarily written in Python. Its source is publicly available at https://github.com/9001/copyparty, and it has 47,235 GitHub stars.