Installation

Copr provides two main client tools for interacting with the build service: the command-line interface (copr-cli) and the Python client library (python-copr). Choose the tool that best fits your workflow.

copr-cli

The copr-cli tool is a command-line interface for managing Copr projects, submitting builds, and monitoring build status.

Install on Fedora

On Fedora systems, install copr-cli using DNF:

sudo dnf install copr-cli

Install on RHEL/CentOS

For RHEL and CentOS systems, first enable EPEL:

sudo dnf install epel-release
sudo dnf install copr-cli

Install from PyPI

You can also install copr-cli using pip:

pip install copr-cli

Installing via pip may not include man pages and shell completions. The distribution package is recommended.

Verify installation

Check that copr-cli is installed correctly:

copr-cli --version

You should see output similar to:

copr-cli 2.4

Configuration

Generate API token

Before using copr-cli, you need to configure authentication:

Visit copr.fedorainfracloud.org and log in with your FAS account.

Get your API token

Navigate to the API page.

Save configuration

Copy the generated configuration to ~/.config/copr:

mkdir -p ~/.config
# Copy the configuration from the API page
nano ~/.config/copr

Set appropriate permissions:

chmod 600 ~/.config/copr

Your configuration file should look like this:

~/.config/copr

[copr-cli]
login = your-username
username = your-username
token = your-api-token-here
copr_url = https://copr.fedorainfracloud.org

Alternative: Use GSSAPI authentication

If you have Kerberos configured, copr-cli can use GSSAPI authentication automatically without an API token:

# Get a Kerberos ticket
kinit [email protected]

# Use copr-cli (no token needed)
copr-cli list

GSSAPI authentication is enabled by default in copr-cli. You can disable it in your configuration file by adding gssapi = False.

python-copr

The python-copr library provides programmatic access to Copr functionality. Use this library to integrate Copr into your Python applications and automation scripts.

Install on Fedora

Install the Python 3 client library:

sudo dnf install python3-copr

Install on RHEL/CentOS

First enable EPEL, then install:

sudo dnf install epel-release
sudo dnf install python3-copr

Install from PyPI

Install using pip:

pip install copr

For development installations:

git clone https://github.com/fedora-copr/copr.git
cd copr/python
pip install -e .

Verify installation

Test the installation in Python:

import copr.v3
print(copr.v3.__version__)

Basic usage

copr-cli examples

# List your projects
copr-cli list

# List someone else's projects
copr-cli list username

python-copr examples

Here’s a basic example using the python-copr library:

from copr.v3 import Client

# Initialize client (uses ~/.config/copr)
client = Client.create_from_config_file()

# List projects
projects = client.project_proxy.get_list(ownername="your-username")
for project in projects:
    print(f"{project.name}: {project.description}")

# Get project details
project = client.project_proxy.get(ownername="your-username", projectname="my-project")
print(f"Project: {project.full_name}")
print(f"Chroots: {project.chroot_repos.keys()}")

# Submit a build
build = client.build_proxy.create_from_urls(
    ownername="your-username",
    projectname="my-project",
    urls=["https://example.com/package.src.rpm"]
)
print(f"Build ID: {build.id}")
print(f"Build URL: https://copr.fedorainfracloud.org/coprs/build/{build.id}/")

# Monitor build status
import time
while build.state in ["pending", "running"]:
    time.sleep(30)
    build = client.build_proxy.get(build.id)
    print(f"Build state: {build.state}")

print(f"Build finished: {build.state}")

Building from Git with python-copr

from copr.v3 import Client

client = Client.create_from_config_file()

# Build from Git repository
build = client.build_proxy.create_from_scm(
    ownername="your-username",
    projectname="my-project",
    scm_type="git",
    clone_url="https://github.com/user/repo.git",
    committish="main",
    spec="package.spec",
    scm_subdir="",
    srpm_build_method="rpkg"
)

print(f"Build submitted: {build.id}")

Shell completion

Enable shell completion for copr-cli to get command and argument suggestions.

Bash

Add to your ~/.bashrc:

eval "$(register-python-argcomplete copr-cli)"

Then reload:

source ~/.bashrc

Zsh

Add to your ~/.zshrc:

autoload -U bashcompinit
bashcompinit
eval "$(register-python-argcomplete copr-cli)"

Shell completion requires the argcomplete package. Install it with pip install argcomplete if not already available.

Getting help

Command-line help

View available commands:

copr-cli --help

Get help for a specific command:

copr-cli build --help
copr-cli create --help

Man pages

Read the manual page:

man copr-cli

Python library documentation

The python-copr library includes comprehensive documentation:

API documentation: python-copr.readthedocs.org
Source code: github.com/fedora-copr/copr/tree/main/python

You can also use Python’s built-in help:

import copr.v3
help(copr.v3.Client)
help(copr.v3.BuildProxy)

Troubleshooting

Command not found

If copr-cli command is not found after installation:

Verify the package is installed: rpm -q copr-cli
Check your PATH includes /usr/bin
Try logging out and back in

Authentication failures

If you get “Authentication failed” errors:

Verify your ~/.config/copr file exists and has correct permissions
Check that the token hasn’t expired (regenerate from web UI if needed)
Ensure the file format matches the example above
Try with --debug flag for more details: copr-cli --debug list

Import errors (Python)

If you get ImportError: No module named copr:

Verify installation: pip list | grep copr or rpm -q python3-copr
Check you’re using the correct Python version
If using virtual environments, ensure the package is installed in the active environment

SSL certificate errors

If you encounter SSL certificate verification errors:

# Temporarily disable SSL verification (not recommended for production)
export COPR_INSECURE=1
copr-cli list

Or update your system’s CA certificates:

sudo dnf update ca-certificates

Next steps

Quickstart

Follow the quickstart guide to create your first project and build

API reference

Explore the full Copr API documentation

Build sources

Learn about different build source types and methods

Automation

Set up webhooks and automated builds

Get Started

User Guide

CLI Tool

Advanced

​Installation

​copr-cli

​Install on Fedora

​Install on RHEL/CentOS

​Install from PyPI

​Verify installation

​Configuration

​Generate API token

​Alternative: Use GSSAPI authentication

​python-copr

​Install on Fedora

​Install on RHEL/CentOS

​Install from PyPI

​Verify installation

​Basic usage

​copr-cli examples

​python-copr examples

​Building from Git with python-copr

​Shell completion

​Bash

​Zsh

​Getting help

​Command-line help

​Man pages

​Python library documentation

​Troubleshooting

​Command not found

​Authentication failures

​Import errors (Python)

​SSL certificate errors

​Next steps

Quickstart

API reference

Build sources

Automation

Build docs developers (and LLMs) love

Installation

copr-cli

Install on Fedora

Install on RHEL/CentOS

Install from PyPI

Verify installation

Configuration

Generate API token

Alternative: Use GSSAPI authentication

python-copr

Install on Fedora

Install on RHEL/CentOS

Install from PyPI

Verify installation

Basic usage

copr-cli examples

python-copr examples

Building from Git with python-copr

Shell completion

Bash

Zsh

Getting help

Command-line help

Man pages

Python library documentation

Troubleshooting

Command not found

Authentication failures

Import errors (Python)

SSL certificate errors

Next steps