Quickstart

Get copyparty running in under 5 minutes

Get copyparty

The fastest way to get started is to download and run the self-extracting Python script:

1. Download copyparty

   Linux / macOS

   # Download the self-extracting script
   curl -LO https://github.com/9001/copyparty/releases/latest/download/copyparty-sfx.py
   
   # Make it executable
   chmod +x copyparty-sfx.py
   
   # Run it
   python3 copyparty-sfx.py
   

   Windows

   Download copyparty-sfx.py and double-click it, or run:

   python copyparty-sfx.py
   

   Or download the Windows executable:

   # Download copyparty.exe
   curl -LO https://github.com/9001/copyparty/releases/latest/download/copyparty.exe
   
   # Run it
   .\copyparty.exe
   

   The sfx is a self-extractor which unpacks an embedded tar.gz into your temp directory. If this concerns you, use the zipapp or PyPI installation instead.

2. Access the web interface

   Open your browser and navigate to:

   http://127.0.0.1:3923
   

   You should see the copyparty web interface with the current directory listed.

   By default, copyparty gives everyone read/write access to the current folder. This is fine for testing, but you’ll want to configure proper permissions for production use.

3. Install optional features (recommended)

   For thumbnails, media indexing, and audio transcoding:

   Debian / Ubuntu

   sudo apt install --no-install-recommends python3-pil ffmpeg
   

   Fedora / RHEL

   # Enable rpmfusion first
   sudo dnf install python3-pillow ffmpeg --allowerasing
   

   Alpine

   sudo apk add py3-pillow ffmpeg
   

   macOS (Homebrew)

   brew install pillow ffmpeg
   

   macOS (MacPorts)

   sudo port install py-Pillow ffmpeg
   

   Windows

   # Install Pillow
   python -m pip install --user -U Pillow
   

   Download FFmpeg from ffmpeg.org and add it to your PATH.

   copyparty.exe already includes Pillow and only needs FFmpeg for video thumbnails.

   FreeBSD

   sudo pkg install py39-sqlite3 py39-pillow ffmpeg
   

Configure server options

Now that copyparty is running, let’s configure it with some recommended options:

Enable file indexing

File indexing enables search, deduplication, and the “unpost” feature:

python3 copyparty-sfx.py -e2dsa

What do these flags mean?

• -e2d - Enable database for file metadata
• -e2ds - Index files on server startup
• -e2dsa - Also index on file access
• -e2ts - Enable audio metadata indexing (requires FFmpeg or Mutagen)

Set up permissions

Configure user accounts and volume permissions:

Basic: Read-only for everyone

python3 copyparty-sfx.py -v .::r

Understanding permissions

The permission syntax is: -v SOURCE:URL:PERM1:PERM2:...

• r - Read (browse and download)
• w - Write (upload files)
• m - Move files from this folder
• d - Delete files
• a - Admin (see upload IPs, reload config)
• g - Get-only (download files but can’t list folders)

Format: PERM,user1,user2 grants that permission to those users.

Example: r:rw,ed means everyone can read, only ed can read+write.

Common scenarios

Public file sharing

Share files publicly:

python3 copyparty-sfx.py -v ~/shared:/files:r

Upload dropbox

Create an anonymous upload folder:

python3 copyparty-sfx.py -v ~/uploads:/drop:w:rw,admin -a admin:pass

Anyone can upload, only admin can see files.

Media server

Share your media library:

python3 copyparty-sfx.py -e2ts -v ~/Music:/music:r

Enables audio player and metadata search.

Personal cloud

Private file storage:

python3 copyparty-sfx.py -a user:pass -v ~:/files:rw,user

Only accessible with authentication.

Make it accessible online

To access copyparty from anywhere, use Cloudflare Tunnel:

1. Download cloudflared

   Get cloudflared from Cloudflare’s downloads page

2. Start copyparty with real-IP detection

   python3 copyparty-sfx.py --xff-hdr cf-connecting-ip
   

   This tells copyparty to read the client IP from Cloudflare’s header.

3. Start the tunnel

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

   Cloudflare will display a public URL like https://random-words.trycloudflare.com that you can share.

For production deployments, see the Deployment guides for systemd services, Docker, and reverse proxy setups.

Next steps

Installation methods

Learn about all the ways to install copyparty

Accounts and volumes

Configure detailed permissions and user accounts

Core features

Explore resumable uploads, protocols, and media features

Demo server

Try out a live copyparty instance