# copyparty User Guide

copyparty turns almost any device into a file server with resumable uploads and downloads, usable from *any* web browser — from Internet Explorer 6 to the latest Chrome, and even from a PlayStation Portable or a Nintendo 3DS. The server is a single Python program with **no mandatory dependencies beyond Python itself**; every extra feature (thumbnails, media tags, FTP, SFTP, SMB, WebDAV, TFTP) is an optional add-on you enable only if you want it.

This guide walks you through installing copyparty, sharing folders, uploading and downloading files through the browser, and the everyday features you will actually use. Deep configuration, deployment, security hardening, and internals live in the **Admin Guide**.

> [!NOTE]
> copyparty follows an "inverse unix philosophy" — instead of doing one thing well, it does *everything* and does an *okay* job at all of it. The result is a drop-in service that gives you a huge feature set in a pinch, with zero setup required.

---

## 1. Quick Start

The fastest way to run copyparty is the self-contained **sfx** (self-extracting) build — a single `.py` file that unpacks itself and runs.

=== "Any OS with Python"

    ```bash
    python3 copyparty-sfx.py
    ```

=== "pip (PyPI)"

    ```bash
    python3 -m pip install --user -U copyparty
    copyparty
    ```

=== "Windows (no Python)"

    Download `copyparty.exe` and double-click it, or run from a terminal:

    ```text
    copyparty.exe
    ```

=== "uv"

    ```bash
    uv tool run copyparty
    ```

Running copyparty with **no arguments** gives everyone read/write access to the current folder, then prints a URL you can open:

```text
http://127.0.0.1:3923/
```

> [!WARNING]
> The zero-argument default shares your current folder as read-write **for everyone on the network**. Before exposing copyparty beyond your own machine, set up [accounts and volumes](#6-accounts-and-volumes) so only the right people can read or write.

> [!TIP]
> The default HTTP port is **3923**. Open `http://127.0.0.1:3923/` in any browser to reach the web UI.

### Recommended first options

A few flags dramatically improve the experience:

| Option | What it enables |
|--------|-----------------|
| `-e2dsa` | Index all files so search, dedup, and upload-undo work |
| `-e2ts` | Index audio metadata (needs FFprobe or Mutagen) |
| `-v /mnt/music:/music:r:rw,foo -a foo:bar` | Share `/mnt/music` at URL `/music`, readable by anyone and read-write for user `foo` (password `bar`) |

```bash
python3 copyparty-sfx.py -e2dsa -e2ts -v /mnt/music:/music:r -a foo:bar
```

---

## 2. Installation

### 2.1 Requirements

copyparty needs only **Python** (2.7 or 3.3+). The single mandatory library, `jinja2`, is bundled inside the sfx and exe builds.

> [!NOTE]
> copyparty runs on an extraordinary range of platforms: Windows, Linux, macOS, Android, iOS, FreeBSD, arm32/arm64, ppc64le, s390x, RISC-V, and even SGI IRIX. If it has Python, it probably runs copyparty.

### 2.2 Enabling thumbnails, media indexing, and transcoding

These features need FFmpeg and/or Pillow. Install the recommended extras for your OS:

=== "Debian / Ubuntu"

    ```bash
    apt install --no-install-recommends python3-pil ffmpeg
    ```

=== "Alpine"

    ```bash
    apk add py3-pillow ffmpeg
    ```

=== "Fedora"

    ```bash
    dnf install python3-pillow ffmpeg --allowerasing
    ```

=== "macOS"

    ```bash
    brew install pillow ffmpeg
    ```

=== "Windows"

    ```text
    python -m pip install --user -U Pillow
    ```

    Install [Python](https://www.python.org/downloads/windows/) and FFmpeg manually. Do **not** use `winget` or the Microsoft Store — they break `$PATH`.

> [!IMPORTANT]
> `copyparty.exe` already bundles Pillow, so it only needs FFmpeg for media tags and video thumbnails.

### 2.3 Install methods at a glance

| Method | Command | Notes |
|--------|---------|-------|
| sfx | `python3 copyparty-sfx.py` | Recommended; one file, all features |
| English-only sfx | `python3 copyparty-en.py` | Smaller |
| PyPI | `python3 -m pip install --user -U copyparty` | System Python |
| Windows exe | run `copyparty.exe` | win8+; `copyparty32.exe` for win7 |
| zipapp | `python copyparty.pyz` | Emergency fallback, fewer features |
| Arch | `pacman -S copyparty` | From `extra` |
| Homebrew | `brew install copyparty ffmpeg` | Intel + Apple Silicon |
| Nix | `nix profile install github:9001/copyparty` | Flake-enabled Nix |
| Gentoo | `emerge www-servers/copyparty::guru` | From `::guru` overlay |
| Android | install in Termux | See §15 |
| iOS | install in a-Shell | See §15 |

> [!TIP]
> The sfx is a self-extractor that unpacks an embedded `tar.gz` into `$TEMP`. If that worries you, use the [zipapp](https://github.com/9001/copyparty/releases/latest/download/copyparty.pyz) instead — it runs entirely from the zip without writing temporary files, at slightly lower performance.

---

## 3. The Web Browser Interface

The web UI is copyparty's main surface. Open the server URL and you get a file listing with a toolbar of tabs.

### 3.1 The main tabs

| Tab | Purpose |
|-----|---------|
| `[🔎]` | Search by size, date, path/name, mp3-tags |
| `[🧯]` | Unpost — undo/delete your accidental uploads |
| `[🚀]` / `[🎈]` | The two uploaders (fancy / basic) |
| `[📂]` | mkdir — create directories |
| `[📝]` | New textfile |
| `[📟]` | Send message to the server log or into a textfile |
| `[🎺]` | Audio-player settings |
| `[⚙️]` | General client settings |

### 3.2 Hotkeys

copyparty has a rich keyboard interface (keys are always QWERTY positions):

| Key | Action |
|-----|--------|
| `?` | Show the hotkey help overlay |
| `B` | Toggle breadcrumbs / [navpane](#33-navpane) |
| `I` / `K` | Previous / next folder |
| `M` | Parent folder (or collapse current) |
| `G` | Toggle list / grid view |
| `T` | Toggle thumbnails / icons |
| `ctrl-X` / `ctrl-C` / `ctrl-V` | Cut / copy / paste selected files |
| `ctrl-K` | Delete selected files/folders |
| `Y` | Download selected files |
| `F2` | [Batch rename](#311-batch-rename) |
| `ESC` | Close the current overlay |

When a media file is open, more keys appear:

- **Audio:** `J/L` prev/next song, `U/O` skip 10 s, `0..9` jump to 0–90 %, `P` play/pause.
- **Images/video:** `J/L` or `←/→` prev/next, `F` fullscreen, `R` rotate, `Home/End` first/last.
- **Video extras:** `M` mute, `[` / `]` set loop range, `V` loop entire file.
- **Markdown editor:** `^s` save, `^h` header, `^k` autoformat table, `^e` toggle editor/preview.

### 3.3 Navpane

Press `B` (or click the `🌲`) to switch between the breadcrumb path and a tree-browser sidebar (the navpane).

- `[+]` / `[-]` (or hotkeys `A`/`D`) adjust the tree width.
- `[🎯]` jumps to the currently open folder.
- `[📃]` toggles between showing folders and textfiles.
- `[👀]` shows the full name on hover when wordwrap is off.

### 3.4 Thumbnails and grid view

Press `g` (or click `田` bottom-right) to toggle grid view; `t` toggles between icons and thumbnails.

- Thumbnails are generated from images (Pillow / pyvips / FFmpeg), videos (FFmpeg), and audio (FFmpeg spectrograms).
- Enable for a single page by adding `?imgs` to a link; disable with `?imgs=0`.
- A folder's thumbnail is taken from an image named `folder.png`, `folder.jpg`, `cover.png`, or `cover.jpg` (in that priority order).

> [!NOTE]
> pyvips produces higher-quality thumbnails ~3× faster than Pillow, and Pillow is ~3× faster than FFmpeg. Your admin chooses which engines are available.

> [!TIP]
> If thumbnails show as a colorful box with the filetype instead of a preview, the server is missing FFmpeg or Pillow — ask your admin to install one of them.

### 3.5 Zip / tar downloads

Download a whole folder (or a selection of files) as an archive. Choose the archive type in the `[⚙️] config` tab, or append a URL suffix directly:

| Name | URL suffix | Description |
|------|-----------|-------------|
| tar | `?tar` | Plain gnutar; pairs with `curl \| tar -xv` |
| pax | `?tar=pax` | Futureproof pax tar |
| tgz | `?tar=gz` | gzip-compressed tar |
| txz | `?tar=xz` | xz/lzma-compressed tar (slow) |
| zip | `?zip` | Works everywhere |
| zip_dos | `?zip=dos` | cp437, fixes glitchy filenames on old Windows |
| zip_crc | `?zip=crc` | cp437 with early CRC32, for truly ancient software |

```bash
# download a folder as a tar stream and extract on the fly
curl 'http://127.0.0.1:3923/music/?tar' | tar -xv
```

> [!TIP]
> Append `?tar&opus` or `?tar&mp3` to transcode every audio file in the folder before adding it to the archive — perfect when your server only has FLACs and you need MP3s on your phone before takeoff. Add `&name=foo` to rename the top-level folder, or `&j` / `&w` to get jpeg/webm thumbnails instead of originals.

### 3.6 Uploading

Drag files or folders into the browser window to upload. You can also:

- Select files in your file explorer and press `CTRL-V` inside the browser.
- Use the [command-line uploader](#13-non-browser-clients) `u2c.py`.
- Use curl, ShareX, ishare, etc.

There are two uploaders:

- `[🎈] bup` — the **basic** uploader; works in almost every browser since Netscape 4.0.
- `[🚀] up2k` — the **fancy** one, and the default for drag-and-drop.

**up2k advantages:**

- Drop whole folders (added recursively).
- Files are split into checksummed chunks, so uploads **auto-resume** after a network drop, browser restart, or reboot — just upload the same files again.
- The server detects corruption and re-requests only the affected chunks.
- Already-existing files are skipped (not re-uploaded).
- **No filesize limit**, even behind a proxy that caps request size (e.g. Cloudflare).
- The file's last-modified timestamp is preserved.

> [!IMPORTANT]
> It is perfectly safe to restart or upgrade copyparty while someone is uploading — all up2k clients resume cleanly.

The up2k panel has these controls:

- **parallel uploads** — how many chunks to send at once.
- `[🥔]` — a simpler "potato" UI for faster uploads from slow devices.
- `[🛡️]` — overwrite policy: `🛡️` never (new filename), `🕒` overwrite if older, `♻️` always overwrite if different.
- `[🎲]` — generate random filenames.
- `[🔎]` — switch between Upload and [File-Search](#37-file-search) mode.

Tabs below show progress: `[ok]` succeeded, `[ng]` failed/rejected, `[busy]` hashing/uploading, `[que]` queued, `[done]` combined.

> [!TIP]
> Turn on `favicon` in the `[⚙️] settings` tab and the browser-tab icon becomes an upload progress indicator. The `[🔔]` / `[🔊]` switches enable visible and audible completion notifications.

### 3.7 File-Search

When you drag files into the browser you get **two** dropzones: **Upload** and **Search**. Drop into Search and copyparty hashes the files locally, sends only the hashes, and tells you whether identical contents already exist on the server.

- Matches land in `[ok]` with a link to where the file lives; non-matches land in `[ng]`.
- On a phone, flip the `[🔎]` switch green before tapping the big yellow Search button.

> [!NOTE]
> File-search requires the server admin to have enabled indexing (`-e2dsa`). If search returns nothing, indexing may be off.

### 3.8 Unpost — undo your uploads

The `[🧯]` tab lets you delete files **you** uploaded, even without normal move/delete permission — but only within the `--unpost` window (default 12 hours) and only if the server runs with `-e2d`. This is also where you abort unfinished uploads (refresh the page first).

### 3.9 Self-destruct uploads

If the admin enabled the `lifetime` rule on a volume, uploads expire automatically after a set time. You can choose a *shorter* lifetime in the up2k UI when uploading into such a folder.

### 3.10 File manager

Select a file by clicking on its line (not the link), then:

- `space` toggle, `up/down` move cursor, `shift-up/down` select-and-move, shift-click for range-select.
- `ctrl-x` cut, `ctrl-c` copy, `ctrl-v` paste (in another folder or even another browser tab), `F2` rename.

Cut/copy/delete/rename require the matching permission on the folder.

### 3.11 Batch rename

Select files and press `F2`. Basic mode renames the chosen files; **advanced** mode renames by rules using regex on the original name and/or the file's tags (artist/title/…).

- `regex` is matched against the original filename; non-matching files are skipped.
- `format` is the new name, drawing from regex capture groups `(1)`, `(2)`, … and tag names like `(artist)`, `(title)`, `(ext)`.
- Functions `$lpad(text,len,char)` and `$rpad(...)` are available; counters `.n.s` (nth in selection) and `.n.d` (nth in folder) help with numbering.

Example — file `meganeko - Eclipse - 07 Sirius A.mp3` with tags `Artist:meganeko`, `Title:Sirius A`, `tn:7`:

```text
regex  = (.*) - (.*) - ([0-9]{2}) (.*)
format = (3). (1) - (4)
output = 07. meganeko - Sirius A.mp3
```

### 3.12 Shares

When the admin enables shares (`--shr`), click the bottom-right `share` button to create a temporary link to the current folder, or select files/a folder first to share only those. When creating a share you can set:

- Password protection.
- Expiry time (`0` or blank = never).
- Allow visitors to upload (if you have write access).

You can delete your own shares from the control panel.

> [!CAUTION]
> A share link bypasses normal auth for that specific path — but it does **not** replace proper [accounts and volumes](#6-accounts-and-volumes). Restrict any volume you don't intend to expose; reverse-proxy rules on just the share folder are not sufficient.

### 3.13 RSS and OPDS feeds

- **RSS:** if enabled (volflag `rss` / `--rss`), append `?rss` to a folder URL to get a feed (with iTunes metadata for podcast readers). Parameters include `recursive`, `fext=mp3,opus`, `nf=30` (limit), and `sort=m` (by mtime).
- **OPDS:** for e-readers; append `?opds` to a folder URL and point your reader at it (e.g. `https://copyparty.example/books/?opds`).

### 3.14 Recent uploads

Click "show recent uploads" in the control panel to list recent uploads. Admins also see uploader IP and time. For *your own* uploads, the [🧯 unpost](#38-unpost--undo-your-uploads) tab is better because it lets you undo them.

---

## 4. Media Player

copyparty plays almost every audio format. These usually play without FFmpeg: `aac flac m4a mp3 ogg opus wav`; anything else is transcoded on-demand if the server has FFmpeg.

- Add `?v` to any audio/video/image link to open it in the media player.
- The player shows the audio waveform in the seekbar and supports OS lock-screen controls.
- Video files can be played as **audio only**, saving bandwidth.

Open the `[🎺]` settings tab to configure:

- **Switches:** `[🔁]` repeat one, `[🔀]` shuffle folder, `[preload]` start loading the next track early, `[os-ctl]` enable lock-screen controls, `[art]` show album art on lock screen.
- **At end of folder:** `[loop]` keep looping, `[next]` play into next folder.
- **Transcode:** `[flac]`/`[aac]`/`[oth]` decide which source formats get converted.
- **Transcode to:** `[opus]` (best on Android/PC), `[awo]`/`[caf]` (iPhone variants), `[mp3]` (works everywhere), `[flac]`/`[wav]` (lossless; admin must allow with `--allow-flac`/`--allow-wav`).

### 4.1 Playlists

Click an `.m3u`/`.m3u8` file to **Play** or **Edit** it. Playlists may reference songs across folders, but filekeys/dirkeys are not supported, so the listener needs read or get access to each file.

To build a playlist in copyparty itself, enable `[📻]` in the `[🎺]` tab — `[📻add]` adds the current/selected songs and `[📻copy]` puts the playlist on your clipboard, ready to paste into a new `.m3u` textfile.

### 4.2 Audio equalizer

The `[🎺]` tab includes an equalizer and a dynamic-range compressor; it can also boost volume and adjust stereo width. Leaving the EQ enabled (even flat) reduces the gap between songs, helping gapless albums.

> [!NOTE]
> The equalizer is unavailable on iPhones/iPads because Safari's AudioContext currently breaks background playback.

---

## 5. Viewing Files

### 5.1 Textfile viewer

Click `-txt-` next to a textfile to open the viewer. Toolbar:

- `✏️ edit` — open the textfile editor.
- `📡 follow` — stream new lines in realtime, like `tail -f`. Add `&tail` to the URL to start following immediately.

Terminal color codes render correctly.

### 5.2 Markdown viewer and editor

Markdown files render with a built-in viewer, and there are two editors. Inline clickable thumbnails are supported — add `<!-- th -->` to the document, then `!th[l](your.jpg)` (`l`/`r` = left/right align).

**Markdown variables:** documents can contain server-side variables like `{{self.ip}}` (the client's IP) or `{{srv.htime}}` (server time), expanded before display.

### 5.3 Image gallery and comics

The grid view doubles as an image gallery with a webm player and a CBZ manga/comics reader.

### 5.4 Other tricks

- Link a timestamp in an audio file by adding it to the URL, e.g. `&t=1:20` after the `#af-...` anchor.
- Get a plaintext listing with `?ls=t`, or a colored terminal listing with `?ls=v`.
- Files named `.prologue.html` / `.epilogue.html` render before/after directory listings.
- `README.md` renders after a listing; `PREADME.md` renders above it.

---

## 6. Accounts and Volumes

Permissions in copyparty are **per-folder, per-user**. A **volume** maps a URL (like `/music/`) to a real folder on the server (like `/mnt/music`); an **account** is a username + password.

> [!TIP]
> Once your setup grows beyond a couple of folders, switch from command-line flags to a [config file](#7-configuration-files) — it is far easier to manage and can be reloaded without restarting.

### 6.1 Permission letters

| Letter | Permission |
|--------|-----------|
| `r` | **read** — browse, download, zip/tar, see filekeys/dirkeys |
| `w` | **write** — upload, move/copy files *into* this folder |
| `m` | **move** — move files/folders *out of* this folder |
| `d` | **delete** — delete files/folders |
| `.` | **dots** — may request to see dotfiles |
| `g` | **get** — download only; cannot list folder or zip/tar |
| `G` | **upget** — like `g`, but uploaders also see their own [filekeys](#9-filekeys-and-dirkeys) |
| `h` | **html** — like `g`, but folders return their `index.html` |
| `a` | **admin** — see upload times, uploader IPs, reload config |
| `A` | **all** — equivalent to `rwmda.` |

### 6.2 Configuring with command-line flags

- `-a user:pwd` adds an account.
- `-v src:dst:perm:perm:…` adds a volume — local path, URL path, then one or more permission groups.

Examples:

```bash
# three accounts
-a u1:p1 -a u2:p2 -a u3:p3

# /srv as the webroot, read-only for everyone
-v /srv::r

# /mnt/music at /music, read-only for u1/u2, read-write for u3
-v /mnt/music:music:r,u1,u2:rw,u3

# write-only dropbox for u1, read-move for u2
-v /mnt/incoming:inc:w,u1:rm,u2
```

> [!NOTE]
> The group `@acct` always contains every logged-in user, so `-v /mnt/music:music:r,@acct` grants read to anyone who has logged in. To grant access only to users who are *not* logged in, use `*,-@acct`. You can subtract a single user from a group, e.g. `@admins,-james`.

### 6.3 Passwords in URLs

You can pass a password in a link by appending `?pw=hunter2` (use `&pw=` if the URL already has parameters). With `--usernames` enabled, use `?pw=username:password`.

> [!WARNING]
> Anyone who bruteforces a password gets banned per `--ban-pw` (default: 24-hour ban after 9 failed attempts in 1 hour). If you keep seeing `thank you for playing`, you have been banned — ask your admin.

---

## 7. Configuration Files

For anything beyond a trivial setup, use a config file and run `python copyparty-sfx.py -c foobar.conf`. The same volumes and accounts from §6.2 look like this:

```yaml
[accounts]
  u1: p1   # create account "u1" with password "p1"
  u2: p2   #  (comments need TWO spaces before the # )

[groups]
  g1: u1, u2

[/]            # this URL maps to...
  /srv         # ...this server folder
  accs:
    r: *       # read-only for everyone

[/music]
  /mnt/music
  accs:
    r: u1, u2  # only these can read
    rw: u3     # u3 can read-write

[/inc]
  /mnt/incoming
  accs:
    w: u1      # upload-only
    rm: u2     # browse + move out
```

> [!TIP]
> You can reload accounts and volumes **without restarting** — run `systemctl reload copyparty` (or `kill -s USR1`), or click `[reload cfg]` in the control panel if you have admin (`a`) in any volume. Changes to the `[global]` section still require a restart.

> [!NOTE]
> You can also point copyparty at a config with the environment variable `PRTY_CONFIG=foobar.conf`, which is handy in Docker.

---

## 8. Searching

When started with `-e2dsa`, copyparty indexes your files, which both prevents duplicate uploads and makes volumes searchable from the `[🔎]` tab.

- Search by **size**, **date**, **path/name**, or **mp3 tags**.
- Name/path queries are space-separated and AND-ed; prefix a word with `-` to exclude it.
  - `shibayan -bossa` → folders containing `shibayan` but not `bossa`.
- The `raw` field accepts richer SQL-like queries, e.g. `( tags like *nhato* or tags like *taishi* )`.

To search by music tags, also start the server with `-e2ts` so tags get indexed.

> [!NOTE]
> If you have a "wark" (copyparty's file identifier), search for it in the `[🔎]` tab by putting `w = kFpDiztbZc8Z1Lzi` in the `raw` field.

---

## 9. Filekeys and Dirkeys

These let an admin share specific files or folders without granting full read access — you only need the `g` (get) permission plus the correct key.

- **Filekeys** (volflag `fk`): each file gets a per-file access key shown as `?k=...` at the end of its URL. A `g`-user must supply that exact URL or get a 404.
- **Dirkeys** (volflag `dk`): each folder gets a key granting read access to that folder.

If your admin enabled these, links you share must include the `?k=` key. With permission `wG`, you can upload files and receive your own working links without seeing anyone else's uploads.

---

## 10. Accessing copyparty from Other Protocols

Besides the browser, copyparty can speak several network protocols if the admin enables them. As a user, here is how to connect.

### 10.1 WebDAV (mount as a drive)

WebDAV lets you mount copyparty straight from your OS file explorer. Click the **connect** button in the control panel for exact instructions.

=== "Windows"

    Right-click *My Computer* → *Map network drive* → Folder: `http://192.168.123.1:3923/`. Type your password in the **username** field (the password field can be empty).

=== "macOS"

    Finder → *Go* → *Connect to Server…* → `http://192.168.123.1:3923/`

=== "Linux (rclone, recommended)"

    rclone's WebDAV backend is the fastest and most reliable client.

> [!WARNING]
> Windows' built-in WebDAV client is buggy. If reconnecting after a reboot fails, try logging in with a wrong password first then the correct one — or just put your password in the username field. rclone avoids all of these bugs.

### 10.2 FTP / FTPS

If the admin started `--ftp 3921` (or `--ftps` for TLS), connect with any FTP client:

```bash
lftp -u k,wark -p 3921 127.0.0.1 -e ls          # plaintext FTP
curl --ssl-reqd ftp://127.0.0.1:3990/           # encrypted FTPS
```

Log in with any username plus your password, or put your password in the username field (unless `--usernames` is enabled). FTP uploads are **not** resumable — delete and restart if interrupted.

### 10.3 SFTP

If the admin started `--sftp 3922`, connect with any SSH/SFTP client. Authentication is by SSH key by default; password login works only if the admin enabled `--sftp-pw`.

### 10.4 SMB / CIFS

If enabled (`--smb` read-only or `--smbw` read-write), copyparty appears as a Windows network share. Authenticate with either `username` + `password`, or username `$password` + password `k`.

> [!CAUTION]
> SMB is **slow and not recommended over the internet** — the built-in Windows WebDAV client is ~5× faster, and rclone-WebDAV ~30× faster. Use SMB only on a trusted LAN.

### 10.5 TFTP

If enabled (`--tftp 3969`), copyparty serves TFTP — mostly useful for talking to very old hardware (firmware on 1990s devices):

```bash
curl --tftp-blksize 1428 tftp://127.0.0.1:3969/firmware.bin
```

---

## 11. Non-Browser Clients

copyparty is friendly to scripts and command-line tools.

### 11.1 curl / wget upload

```bash
# upload, get HTML back
curl -F f=@movie.mkv http://127.0.0.1:3923/?pw=wark

# upload, get a plain hotlink URL back
curl -F f=@movie.mkv 'http://127.0.0.1:3923/?want=url&pw=wark'

# stream stdin to a file (chunked)
curl -H pw:wark -T- http://127.0.0.1:3923/ < movie.mkv

# append to an existing file
echo hey | curl -H pw:wark -T- http://127.0.0.1:3923/logfile.txt?apnd
```

You can supply a password via header `PW: hunter2`, cookie `cppwd=hunter2`, url-param `?pw=hunter2`, or basic-auth (as username or password).

> [!IMPORTANT]
> curl will **not** send the original filename when you combine `-T` with url-params. Always leave a trailing slash in URLs unless you intend to override the filename.

### 11.2 u2c.py — the command-line up2k client

`u2c.py` is the Python uploader with resumable uploads, file-search, and folder sync. Download it from the control panel → connect → `u2c.py`, or from the repo's `bin/` folder.

### 11.3 Folder sync

```bash
u2c.py --dr  /local/folder  https://server/volume/
```

`--dr` verifies checksums, uploads in parallel, and deletes unexpected server files after upload (so renames are cheap — copyparty renames server-side instead of re-uploading).

> [!NOTE]
> copyparty does **one-way** sync only (client→server or server→client); full bidirectional sync like Nextcloud/Syncthing is intentionally never supported. You can, however, safely combine copyparty with Syncthing on the same folders.

### 11.4 FUSE — mount the server as a filesystem

`partyfuse.py` (cross-platform Python) mounts a copyparty server read-only as a local filesystem. rclone gives ~5× the performance and also supports writing.

---

## 12. Making it Reachable Over the Internet

The quickest way to expose a local copyparty is a **Cloudflare quick-tunnel**:

```bash
cloudflared tunnel --url http://127.0.0.1:3923
```

This prints a public URL anyone can use to browse your files or upload to you.

> [!IMPORTANT]
> When users connect through Cloudflare (or any reverse proxy), start copyparty with `--xff-hdr cf-connecting-ip` so it sees the real client IP. Otherwise everyone may share one IP and get each other banned. See the Admin Guide for full reverse-proxy and real-IP setup.

---

## 13. Performance Tips (Client Side)

When uploading, you can speed things up:

- In the `[⚙️] settings` tab, enable `[wasm]` when uploading from a very fast SSD with Chrome/Firefox to use all CPU cores for hashing. Do **not** enable it on Safari or old browsers.
- **Chrome is faster than Firefox** for hashing (up to 90 %) and for uploading over very fast links (up to 40 %).
- If your CPU is the bottleneck, hide the upload list by switching away from the `[🚀]` tab (or switch to the `[🥔]` potato UI) — up to 30 % faster.
- On Android-Chrome, increase "parallel uploads" for higher speed.

> [!TIP]
> Defaults are usually fine — expect roughly **8 GiB/s** download and **1 GiB/s** upload on a fast LAN.

---

## 14. Mobile Apps and Shortcuts

- **Android:** [PartyUP!](https://f-droid.org/packages/me.ocv.partyup/) is a one-tap upload client (not the full server). To run the *server* on Android, install it in Termux (see below).
- **iOS:** there is no app, but an [upload-to-copyparty shortcut](https://www.icloud.com/shortcuts/41e98dd985cb4d3bb433222bc1e9e770) can strip EXIF and upload files, pics, vids, links, and clipboard contents.

### 14.1 Run the server on Android (Termux)

Install [Termux](https://termux.com/) and `Termux:API`, then paste:

```sh
yes | pkg upgrade && termux-setup-storage && yes | pkg install python termux-api && python -m ensurepip && python -m pip install --user -U copyparty
```

Launch with `copyparty` (add `--qr` for a QR code to your external IP).

### 14.2 Run the server on iOS (a-Shell)

Install [a-Shell](https://apps.apple.com/us/app/a-shell/id1473805438), then:

```sh
curl -L https://github.com/9001/copyparty/raw/refs/heads/hovudstraum/contrib/setup-ashell.sh | sh
```

This creates a config file `cpc` and a `cpp` command to launch copyparty.

---

## 15. Browser Support

**TLDR: yes.** copyparty works in essentially every browser ever made.

| Feature | IE6 | IE9 | IE11 | Firefox 52 | Chrome 49 | iOS | Android |
|---------|-----|-----|------|-----------|-----------|-----|---------|
| Browse files | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Basic uploader | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| up2k (resumable) | — | — | slow | ✅ | ✅ | ✅ | ✅ |
| Thumbnail view | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Media player | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Markdown editor | — | — | text only | ✅ | ✅ | ✅ | ✅ |

Even text browsers (links, lynx, w3m) and exotic clients (Sony PSP, Nintendo 3DS, an SGI O2 with 64 MiB RAM) can browse and often upload — try appending `?b=u` for the simplified HTML uploader on very old clients.

---

## 16. Troubleshooting

### Error: `thank you for playing`

**Cause:** Your IP was banned for too many failed password attempts (or your real IP is hidden behind a reverse proxy and someone else on that shared IP triggered the ban).
**Solution:** Wait out the ban, or ask the admin to configure real-IP detection (`--xff-hdr`). See §12.
**Prevention:** Type passwords carefully; behind Cloudflare, the admin should set `--xff-hdr cf-connecting-ip`.

### Error: Thumbnails show a colored box with the filetype

**Cause:** The server has no FFmpeg or Pillow installed.
**Solution:** Ask the admin to install FFmpeg or Pillow (§2.2).
**Prevention:** Install the recommended media dependencies up front.

### Error: Thumbnails broken only for iPhone photos/videos

**Cause:** The Docker image and bootable builds can't read HEIF/HEIC images or H.265/HEVC video for legal reasons.
**Solution:** Run copyparty natively with `pyvips` (or convert the media first).

### Error: Some thumbnails blank or broken-image

**Cause:** A reverse proxy is stripping the `?th=w` query parameter, or a CDN is mis-caching, or a privacy browser extension is interfering.
**Solution:** Ensure the proxy/CDN preserves the query string; try disabling browser extensions.

### Error: Firefox "Secure Connection Failed" / `SEC_ERROR_BAD_SIGNATURE` with no "Accept the Risk" button

**Cause:** Firefox's certificate store is corrupted.
**Solution:** Exit Firefox and delete `cert9.db` from your Firefox profile folder.

### Error: copyparty thinks you're on HTTP even though the URL is HTTPS

**Cause:** Your reverse proxy isn't sending the `X-Forwarded-Proto: https` header.
**Solution:** Ask the admin to fix the proxy so it forwards that header end to end.

### Error: Drag-and-drop folder upload skips symlinked files

**Cause:** A known Chrome bug ([1317069](https://bugs.chromium.org/p/chromium/issues/detail?id=1317069)) — not a copyparty bug.
**Solution:** Upload the real files directly, not via symlinks.

### Error: Music playback randomly stops on Android

**Cause:** Android's power saver kills the browser's background audio.
**Solution:** Disable power saving for your music browser in the app settings; use a dedicated browser for music.

### Error: Windows "directory iterator got stuck" during upload

**Cause:** Windows max-path-length limit.
**Solution:** Move the files to a shorter path before uploading.

### Issue: Uploads to an anonymous-read WebDAV folder fail to write (Windows)

**Cause:** Windows decides it doesn't need to authenticate, then can't write.
**Solution:** Connect twice (first to an auth-required folder, then your target), or ask the admin to set `--dav-auth`.

---

## 17. FAQ

**Q: Is it `CopyParty` or `copyparty`?**
It's `copyparty` (all lowercase) or `Copyparty` — one word.

**Q: What is a volume?**
A mapping from a URL (e.g. `/music/`) to a folder on the server's filesystem (e.g. `C:\Users\ed\Music`), with its own permissions and options.

**Q: What is a volflag?**
Per-volume configuration. Most global options can be set per-volume as a volflag, and vice-versa.

**Q: Can I block folder listing but still allow direct file links?**
Yes — use the `g` (get) permission instead of `r`. Combine with [filekeys](#9-filekeys-and-dirkeys) to stop filename guessing.

**Q: Can I put the password in a share link?**
Yes — add `?pw=hunter2` to the end (`&pw=` if the URL already has parameters). With `--usernames`, use `?pw=username:password`.

**Q: How do I stop `.hist` folders appearing all over my drive?**
copyparty creates a `.hist` folder per volume for its index/thumbnails. Ask the admin to move them with `--hist` or the `hist` volflag.

**Q: Can copyparty download a file to the server from a URL I give it?**
Yes, via a server-side [hook](https://github.com/9001/copyparty/blob/hovudstraum/bin/hooks/wget.py) — an admin feature.

**Q: My uploads keep failing with corruption — is my data safe?**
up2k checksums every chunk and re-requests only the corrupted ones, so the final file is always verified. Just let it resume.

**Q: Can I upload files bigger than my proxy's request limit?**
Yes. up2k splits files into chunks (default ≤96 MiB to slip under Cloudflare), so there is no effective filesize limit.

**Q: Where do I report bugs?**
At [github.com/9001/copyparty](https://github.com/9001/copyparty/) (primary), or the GitLab/Codeberg mirrors. Include your command-line arguments and config.

---

_Generated June 2026 from 9001/copyparty at 6e75faa. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._