Skip to main content

​
Quickstart guide

This guide will walk you through creating your first Copr project and building your first package. If you’re completely new to Copr, you’re in the right place.
Before you begin, make sure you have a source RPM (SRPM) ready to build. If you don’t have one yet, see the RPM Packaging Guide for instructions.

​
Prerequisites

You’ll need:
  • A Fedora Account System (FAS) account
  • A source RPM file or a Git repository with a .spec file
  • A Fedora-based system with DNF package manager (for CLI installation)

​
Step-by-step setup

1

Create a FAS account

Register for a Fedora Account System account at accounts.fedoraproject.org.This account gives you access to Copr and other Fedora infrastructure services.
2

Log in to Copr

Visit copr.fedorainfracloud.org and click the login link in the top right corner.Use your FAS credentials to authenticate.
3

Generate API token

Navigate to the API token page at copr.fedorainfracloud.org/api.Copy the generated configuration and save it to ~/.config/copr on your local machine:
mkdir -p ~/.config
# Paste the API token configuration into this file
nano ~/.config/copr
The configuration file should look like this:
[copr-cli]
login = your-username
username = your-username  
token = your-api-token
copr_url = https://copr.fedorainfracloud.org
Keep your API token secure. Don’t share it or commit it to version control.
4

Install copr-cli

Install the Copr command-line tool on Fedora:
sudo dnf install copr-cli
Verify the installation:
copr-cli --version
5

Create your first project

Create a project and specify which distributions you want to build for (chroots):
copr-cli create first-project --chroot fedora-rawhide-x86_64
You can specify multiple chroots to build for different distributions:
copr-cli create my-project \
  --chroot fedora-rawhide-x86_64 \
  --chroot fedora-39-x86_64 \
  --chroot epel-9-x86_64
Use copr-cli list-chroots to see all available build targets.
6

Submit your first build

Build from a local SRPM file:
copr-cli build first-project path/to/your-package.src.rpm
Or build from a publicly accessible SRPM URL:
copr-cli build first-project https://example.com/your-package.src.rpm
The command will output a build ID and URL where you can monitor progress:
Created builds: 123456
Watching build(s): (this may be safely interrupted)
Build 123456: succeeded
Builds typically take 5-15 minutes depending on package complexity and builder availability.
7

Enable your repository

Once the build succeeds, users can enable your repository:
sudo dnf copr enable your-username/first-project
Then install your package:
sudo dnf install your-package-name

​
Build from Git repository

Instead of building from SRPMs, you can build directly from Git: 
copr-cli build-scm first-project \
  --clone-url https://github.com/your-username/your-project.git \
  --commit main \
  --subdir ./ \
  --spec your-package.spec \
  --type git \
  --method rpkg

copr-cli build-scm my-project \
  --clone-url https://github.com/example/myapp.git \
  --commit v1.0.0 \
  --spec myapp.spec \
  --type git

​
Web UI workflow

You can also manage everything through the web interface:
1

Create project

Click “New Project” from your Copr homepage and fill in:
  • Project name
  • Chroots (build targets)
  • Optional: description, instructions, external repositories
2

Submit build

Go to your project page and click “Builds” → “New Build”Choose your source type:
  • Upload SRPM directly
  • Provide URL to SRPM
  • Build from Git/DistGit/SVN
  • Build from PyPI or RubyGems
3

Monitor build

Watch build progress on the build detail page. You’ll see:
  • Real-time status for each chroot
  • Build logs
  • Built packages when complete

​
Common build options

​
Background builds

For mass rebuilds or lower-priority builds, use the --background flag: 
copr-cli build first-project package.src.rpm --background

​
Specific chroots

Build only for specific targets instead of all project chroots: 
copr-cli build first-project package.src.rpm \
  --chroot fedora-39-x86_64 \
  --chroot fedora-rawhide-x86_64

​
Build dependencies

If your package depends on another Copr repository or external repository, add it to your project settings: 
copr-cli modify first-project \
  --repo https://copr-be.cloud.fedoraproject.org/results/another-user/another-project/fedora-$releasever-$basearch/

​
Next steps

Build sources

Explore different source types: Git, DistGit, PyPI, RubyGems, and custom scripts

Webhooks

Set up automated builds triggered by Git push events

Team collaboration

Share project access with collaborators and groups

API automation

Use the Copr API and python-copr library for automation

​
Troubleshooting

​
Build failed

Check the build logs for errors:
  1. Click on the build ID from the command output or web UI
  2. Select the failed chroot
  3. Review build.log.gz for compilation errors
  4. Review root.log.gz for dependency issues

​
Authentication errors

If you get authentication errors:
  1. Verify your ~/.config/copr file has the correct token
  2. Check file permissions: chmod 600 ~/.config/copr
  3. Re-generate your API token from the web UI if needed

​
Repository not found

After enabling a repository, if DNF can’t find it:
  1. Ensure the build completed successfully
  2. Wait a few minutes for CDN propagation
  3. Try dnf clean all && dnf makecache
For more help, see the FAQ section or report an issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us