Installation

Detailed installation instructions for copyparty on all supported platforms and environments

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:

1. Download copyparty-sfx.py

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

   Full version

   copyparty-sfx.py - Complete with all languages

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

   English-only

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

   https://github.com/9001/copyparty/releases/latest/download/copyparty-en.py
   
2. 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+

Download copyparty.exe

Includes Pillow built-in. Only needs FFmpeg for video thumbnails and media tags.

Windows 7

Download copyparty32.exe

32-bit version for Windows 7 compatibility.

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

nix profile install github:9001/copyparty

NixOS module

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:

Full image (with all dependencies)

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)

1. Install Termux

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

2. Install Python

   pkg install python
   
3. Install copyparty

   pip install copyparty
   
4. 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)

1. Install a-Shell

   Download a-Shell from the App Store.

2. Install copyparty

   pip install copyparty
   
3. Run copyparty

   copyparty
   

System service integration

For running copyparty as a system service:

systemd (Linux)

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.

Podman + systemd

See contrib/podman-systemd/ for a complete guide on running copyparty in Podman as a systemd service.

OpenRC (Alpine / Gentoo)

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

FreeBSD rc

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)

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.

bubbleparty (bubblewrap)

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

Next steps

Quickstart guide

Learn how to configure and use copyparty

Configuration

Set up accounts, volumes, and advanced features