Installation

Installation methods

copyparty can be installed in multiple ways depending on your platform and preferences.

Self-extracting archive (recommended)

The SFX is the recommended installation method for most users:

Download copyparty-sfx.py

curl -LO https://github.com/9001/copyparty/releases/latest/download/copyparty-sfx.py
chmod +x copyparty-sfx.py

Full version
English-only

copyparty-sfx.py - Complete with all languages

https://github.com/9001/copyparty/releases/latest/download/copyparty-sfx.py

copyparty-en.py - Smaller, English-only version

https://github.com/9001/copyparty/releases/latest/download/copyparty-en.py

Run copyparty

./copyparty-sfx.py

Or with Python explicitly:

python3 copyparty-sfx.py

The SFX is a self-extractor that unpacks an embedded tar.gz into $TEMP. It’s plaintext Python, so you can inspect the code before running.

Official mirrors

If GitHub is unavailable, download from the official mirror:

https://copyparty.eu/py (full SFX)
https://copyparty.eu/en (English-only SFX)
https://copyparty.eu/pyz (zipapp)
https://copyparty.eu/enz (English-only zipapp)

PyPI installation

Install from Python Package Index:

python3 -m pip install --user -U copyparty

Then run with:

copyparty

Why use PyPI over SFX?

Integrates with Python package managers
Easier updates with pip install -U copyparty
Better for automated deployments
Available as a copyparty command system-wide

Windows executable

No Python? Use the standalone Windows executable:

Windows 8+
Windows 7

Download copyparty.exeIncludes Pillow built-in. Only needs FFmpeg for video thumbnails and media tags.

Double-click the .exe to run, or use from command line:

.\copyparty.exe --help

Do not install Python using winget or Microsoft Store - it breaks $PATH. Download from python.org instead.

Zipapp (emergency alternative)

If the SFX doesn’t work, use the zipapp:

curl -LO https://github.com/9001/copyparty/releases/latest/download/copyparty.pyz
python3 copyparty.pyz

The zipapp has slightly worse performance than the SFX but works on systems where the SFX might have issues.

Package managers

Arch Linux

copyparty is in the official Arch repositories:

pacman -S copyparty

Then run with:

systemctl enable --now copyparty

Homebrew (macOS / Linux)

brew install copyparty ffmpeg

Run with:

copyparty

Nix / NixOS

Nix package
NixOS module

nix profile install github:9001/copyparty

Add to your configuration.nix:

{ config, pkgs, ... }:
{
  services.copyparty = {
    enable = true;
    package = pkgs.copyparty;
    # Additional configuration here
  };
}

See the NixOS module documentation for details.

uv (fast Python package runner)

If you have uv installed:

uv tool run copyparty

No installation required - downloads and runs copyparty automatically.

Fedora

Fedora package does not exist yet. Use PyPI or SFX installation.

Docker

copyparty is available as Docker images:

docker run -it --rm \
  -p 3923:3923 \
  -v /path/to/data:/data \
  copyparty/ac

Available image variants:

copyparty/ac - Full image with FFmpeg, Pillow, and all dependencies
copyparty/min - Minimal image (just copyparty, no thumbnails)
copyparty/iv - With libvips for faster thumbnails
copyparty/dj - Debian-based variants

Docker images cannot generate thumbnails for HEIF/HEIC images and H.265/HEVC video due to legal reasons.

See the Docker documentation for more details.

Mobile platforms

Android (Termux)

Install Termux

Download Termux from F-Droid (not Google Play - that version is outdated).

Install Python

pkg install python

Install copyparty

pip install copyparty

Run copyparty

copyparty

Access at http://127.0.0.1:3923

Enable optional features on Android

pkg install python pillow ffmpeg
pip install copyparty pillow mutagen

iOS (a-Shell)

Install a-Shell

Download a-Shell from the App Store.

Install copyparty

pip install copyparty

Run copyparty

copyparty

System service integration

For running copyparty as a system service:

systemd (Linux)
Podman + systemd
OpenRC (Alpine / Gentoo)
FreeBSD rc

Use the provided service file:

# Download the service file
curl -LO https://raw.githubusercontent.com/9001/copyparty/hovudstraum/contrib/systemd/copyparty.service

# Edit to set your configuration
nano copyparty.service

# Install
sudo cp copyparty.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now copyparty

See contrib/systemd/copyparty.service for the template.

Use contrib/openrc/copyparty:

# Download the init script
sudo curl -o /etc/init.d/copyparty https://raw.githubusercontent.com/9001/copyparty/hovudstraum/contrib/openrc/copyparty
sudo chmod +x /etc/init.d/copyparty

# Enable and start
sudo rc-update add copyparty
sudo rc-service copyparty start

Use contrib/rc/copyparty:

# Download the rc script
sudo fetch -o /usr/local/etc/rc.d/copyparty https://raw.githubusercontent.com/9001/copyparty/hovudstraum/contrib/rc/copyparty
sudo chmod +x /usr/local/etc/rc.d/copyparty

# Enable in rc.conf
sudo sysrc copyparty_enable="YES"

# Start the service
sudo service copyparty start

Sandboxing and security

For extra security, run copyparty in a sandbox:

prisonparty (chroot)
bubbleparty (bubblewrap)

Create a minimal chroot environment:

curl -LO https://raw.githubusercontent.com/9001/copyparty/hovudstraum/bin/prisonparty.sh
chmod +x prisonparty.sh
./prisonparty.sh

Very portable and lightweight.

Use bubblewrap for better isolation:

# Install bubblewrap first
# Debian/Ubuntu: apt install bubblewrap
# Arch: pacman -S bubblewrap

curl -LO https://raw.githubusercontent.com/9001/copyparty/hovudstraum/bin/bubbleparty.sh
chmod +x bubbleparty.sh
./bubbleparty.sh

Much better isolation than chroot.

Special environments

Synology NAS / DSM

See the Synology DSM guide for detailed instructions.

Bootable USB / CD-ROM

Not kidding - there’s a bootable edition:

Enterprise Edition bootable image

Boot from USB or CD and run copyparty without any OS installation.

RHEL 8 / Rocky Linux 8

You can run copyparty using the platform Python:

/usr/libexec/platform-python copyparty-sfx.py

Installing optional dependencies

Enhance copyparty with optional features:

Thumbnails (Pillow)

# Debian/Ubuntu
apt install python3-pil

# Alpine
apk add py3-pillow

# Fedora
dnf install python3-pillow

# PyPI
pip install Pillow

Enables image thumbnails and faster image processing.

Faster thumbnails (pyvips)

# Debian/Ubuntu
apt install python3-pyvips

# macOS
brew install vips
pip install pyvips

# PyPI
pip install pyvips

3x faster than Pillow for thumbnails. Required for HEIF/HEIC on some systems.

Video thumbnails and audio transcoding (FFmpeg)

# Debian/Ubuntu
apt install ffmpeg

# Alpine
apk add ffmpeg

# Fedora (requires RPM Fusion)
dnf install ffmpeg

# macOS
brew install ffmpeg

# FreeBSD
pkg install ffmpeg

For Windows, download from ffmpeg.org.

Audio metadata (Mutagen)

pip install mutagen

Read ID3 tags and metadata from audio files. Alternative to using FFprobe.

SFTP server (Paramiko)

pip install paramiko

Enable the SFTP server feature (~700 MiB/s transfer speed).

FTP server (pyftpdlib)

pip install pyftpdlib

Enable the FTP server.

FTPS (FTP with TLS)

pip install pyftpdlib pyopenssl

Enable FTP over TLS.

TFTP server (partftpy)

pip install "partftpy>=0.4.0"

Enable the TFTP server.

Password hashing (argon2-cffi)

pip install argon2-cffi

Use Argon2 for password hashing instead of the default.

Event hooks with ZeroMQ (pyzmq)

pip install pyzmq

Send event notifications via ZeroMQ.

Install all optional dependencies

pip install "copyparty[all]"

This installs: argon2-cffi, paramiko, partftpy, Pillow, pyftpdlib, pyopenssl, pyzmq

Firewall configuration

For servers, open the necessary ports:

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

Port reference:

80/443: HTTP/HTTPS
3921: FTP
3922: SFTP
3923: HTTP (default)
3945: SMB
3969: TFTP (TCP)
3990: FTPS
69: TFTP (UDP)
1900: SSDP
5353: mDNS
12000-12099: Passive FTP

Verifying installation

Check that copyparty is working:

copyparty --version

Or with the SFX:

./copyparty-sfx.py --version

Test run with help:

copyparty --help

Get Started

Core Features

Configuration

Deployment

Guides

Installation methods

Self-extracting archive (recommended)

Official mirrors

PyPI installation

Windows executable

Zipapp (emergency alternative)

Package managers

Arch Linux

Homebrew (macOS / Linux)

Nix / NixOS

uv (fast Python package runner)

Fedora

Docker

Mobile platforms

Android (Termux)

iOS (a-Shell)

System service integration

Sandboxing and security

Special environments

Synology NAS / DSM

Bootable USB / CD-ROM

RHEL 8 / Rocky Linux 8

Installing optional dependencies

Install all optional dependencies

Firewall configuration

Verifying installation

Next steps

Quickstart guide

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

Guides

​Installation methods

​Self-extracting archive (recommended)

​Official mirrors

​PyPI installation

​Windows executable

​Zipapp (emergency alternative)

​Package managers

​Arch Linux

​Homebrew (macOS / Linux)

​Nix / NixOS

​uv (fast Python package runner)

​Fedora

​Docker

​Mobile platforms

​Android (Termux)

​iOS (a-Shell)

​System service integration

​Sandboxing and security

​Special environments

​Synology NAS / DSM

​Bootable USB / CD-ROM

​RHEL 8 / Rocky Linux 8

​Installing optional dependencies

​Install all optional dependencies

​Firewall configuration

​Verifying installation

​Next steps

Quickstart guide

Configuration

Build docs developers (and LLMs) love

Installation methods

Self-extracting archive (recommended)

Official mirrors

PyPI installation

Windows executable

Zipapp (emergency alternative)

Package managers

Arch Linux

Homebrew (macOS / Linux)

Nix / NixOS

uv (fast Python package runner)

Fedora

Docker

Mobile platforms

Android (Termux)

iOS (a-Shell)

System service integration

Sandboxing and security

Special environments

Synology NAS / DSM

Bootable USB / CD-ROM

RHEL 8 / Rocky Linux 8

Installing optional dependencies

Install all optional dependencies

Firewall configuration

Verifying installation

Next steps