<div id="logo" align="center"> <img width="25%" src="https://www.cril.univ-artois.fr/~lecoutre/logoPyCSP3.gif" alt="logo"/> </div> <br /> <h2> PyCSP3 v2.6 _{^{(March 1, 2026)}} </h2> <!-- PyCSP3 is inspired from both [JvCSP3](https://github.com/xcsp3team/XCSP3-Java-Tools/blob/master/doc/JvCSP3v1-1.pdf) (a Java-based API) and [Numberjack](https://github.com/eomahony/Numberjack). -->

This is Version 2.6 of PyCSP3, a library in Python (version 3.10 or later) for modeling combinatorial constrained problems; see www.pycsp.org. With PyCSP3, it is possible to generate instances of:

1. CSP (Constraint Satisfaction Problem)
2. COP (Constraint Optimization Problem)

in format XCSP3; see www.xcsp.org. Currently, PyCSP3 is targeted to XCSP3-core, which allows us to use integer variables (with finite domains) and popular constraints. Note that:

• a dedicated website with more than 60 Jupyter notebooks is available
• a well-documented guide is available
• PyCSP3 is available as a PyPi package
• a GitHub repository with more than 340 models is available at pycsp3-models

At this stage, one can run two embedded solvers:

• the constraint solver ACE, with the option -solve or the option -solver=ace
• the constraint solver Choco, with the option -solver=choco

<!-- Information about how piloting these embedded solvers can be found in [this document](https://github.com/xcsp3team/pycsp3/blob/master/docs/optionsSolvers.pdf). -->

Of course, it is possible to launch on generated XCSP3 instances (files) any solver that recognizes the XCSP3 format. For example, see the solvers involved in the 2022, 2023, 2024 and 2025 Competitions. It is also immediate to run ACE or Choco on XCSP3 instances (files) as the respective executables (jar files) are present in directories pycsp3/solvers/ace and pycsp3/solvers/choco. For example, for running ACE on the XCSP3 instance 'zebra.xml', just execute:

java -jar ACE-YY-MM.jar zebra.xml 

while replacing YY and MM with the current values that are present in the name of the jar file.

Note that it is also possible to pilot solvers with Python; see PyCSP3 Solving Process.

0) Zero Installation from Google Colab

This is an immediate solution for using PyCSP3, with no installation required (you are ready to work in exactly 2 minutes). What you have to do is:

1. build a new notebook on Google colab
2. insert a first code cell for being able to use PyCSP3 in your notebook:

   pip install pycsp3
   

3. test a very basic model by inserting in a second code cell something like:

   from pycsp3 import *
   
   x = VarArray(size=5, dom=range(5))
   
   satisfy(
       AllDifferent(x)
   )  
   
   if solve() is SAT:
       print(values(x))
   

Here, we have an array with 5 variables, we enforce them to be all different, and we display the first solution found by the underlying solver. Just execute these cell codes on Colab. It should return [0, 1, 2, 3, 4].

That's it. However, note that for intensive use, it is better to install PyCSP3 on your computer; see next section.

1) Installation from PyPi

This is the second easiest way of installing PyCSP3.

Note that you need first Python (version 3.10, or later) to be installed. You can do it, for example, from python.org

Installing PyCSP3 (Linux)

Check if 'pip3' is installed. If it is not the case, execute:

sudo apt install python3-pip

Then, install PyCSP3 with the command 'pip3':

sudo pip3 install pycsp3

For using the -solve or -solver options, you need to have Java (at least, version 11) installed:

sudo apt-get install openjdk-11-jdk

Installing PyCSP3 (Mac OS)

If Python 3 is installed on your system, the command 'pip3' should already be present.

Install PyCSP3 with the command 'pip3':

sudo pip3 install pycsp3

For using the -solve or -solver options, you need to have Java (at least, version 11) installed.

Installing PyCSP3 (Windows)

You may need to upgrade 'pip'. Open the console and type:

python -m pip install --upgrade pip

Then, for installing pycsp3, type:

python -m pip install pycsp3

For using the -solve or -solver options, you need to install (at least) Java version 11:

https://www.oracle.com/java/technologies/javase-downloads.html

And add in the PATH the java command, for example, temporally, with the command:

set path=%path%;C:/Program Files/Java/jdk-14.0.1/bin/

You can check the java command by typing in your console:

java --version

Updating the Version of PyCSP3 (for PyPi)

For updating your version of PyCSP3, simply execute:

For linux/Mac:

sudo pip3 install --upgrade pycsp3

For Windows:

python -m pip install --upgrade pycsp3

Using the development version via Github and pip

You can install the current development version (the master branch of this repo) by explicitly indicating that you want to use the repo to pip.

For linux/Mac:

pip3 install --upgrade git+https://github.com/xcsp3team/pycsp3.git

For Windows:

python -m pip install --upgrade git+https://github.com/xcsp3team/pycsp3.git

Working with a Pool of Models

A GitHub repository is now available with more than 340 models at pycsp3-models.

And you can test the compilation of one of these models. For example, at the root of the directory pycsp3-models:

python single/Zebra/Zebra.py (For Linux/Mac)
python single\Zebra\Zebra.py (For Windows)

2) Installation (alternative) by Cloning from GitHub

An alternative to PyPi is to clone the code from GitHub. Here is an illustration for MAC OS. We assume that Python 3 is installed (otherwise, type port install python38 for example), and consequently 'pip3' is also installed. In a console, type:

git clone https://github.com/xcsp3team/pycsp3.git
pip3 install lxml

You may need to update the environment variable 'PYTHONPATH', by typing for example:

export PYTHONPATH=$PYTHONPATH:.

3) Compilation and Examples

We succinctly introduce a few PyCSP3 models, showing how to compile them with different options. However, note that many illustrations are available on www.pycsp.org, notably many models with Jupyter notebooks.

First, we give some general information about compilation.

Compiling PyCSP3 Models

For generating an XCSP3 instance from a PyCSP3 model, you have to execute:

python3 <file> [options]

with:

• <file>: a Python file to be executed, describing a model in PyCSP3
• [options]: possible options to be used when compiling

Among the options, we find:

• -data=<data_value>: allows us to specify the data to be used by the model. It can be:

  • elementary: -data=5
  • a simple list: -data=[9,0,0,3,9]
  • a JSON file: -data=Bibd-3-4-6.json

  Data can then be directly used in the PyCSP3 model by means of a predefined variable data.

• -dataparser=<file>: a Python file for reading/parsing data given under any arbitrary form (e.g., by a text file). See Example Nonogram below, for an illustration.

• -dataexport: exports (saves) the data in JSON format. See Example Nonogram below, for an illustration.

• -variant=<variant_name>: the name of a variant, to be used with function variant(). See Example AllInterval below, for an illustration.

• -solve: attempts to solve the instance with the embedded solver 'Ace'. It requires that Java version 8 (at least) is installed.

• -solver=<solver_name>: attempts to solve the instance with the solver whose name is given. Currently, it can be 'ace' or 'choco'. Important: it requires that Java version 8 (at least) is installed. Information about how piloting these embedded solvers can be found in this document.

• -output=<file_name>: sets the filename of the generated XCSP3 instance (think about the extension .xml)

By default, a file containing the XCSP3 instance is generated, unless you use the option:

• -display: displays the XCSP3 instance in the system standard output, instead of generating an XCSP3 file

Example 1: in console mode

Our first example shows how you can build basic models in console mode. In this example, we just post two variable and two simple binary constraints.

$ python3
Python 3.5.2
>>> from pycsp3 import *
>>> x = Var(range(10))
>>> y = Var(range(10))
>>> satisfy(
       x < y,
       x + y > 15
    )
>>> compile()
>>> if solve() is SAT:
       print(value(x),value(y)) 

Note that to get an XCSP3 file, we call compile().

Example 2: Send+More=Money

This example shows how you can define a model when no data is required from the user. This is the classical crypto-arithmetic puzzle 'Send+More=Money'.

File SendMore.py

from pycsp3 import *

# letters[i] is the digit of the ith letter involved in the equation
s, e, n, d, m, o, r, y = letters = VarArray(size=8, dom=range(10))

satisfy(
    # letters are given different values
    AllDifferent(letters),

    # words cannot start with 0
    [s > 0, m > 0],

    # respecting the mathematical equation
    [s, e, n, d] * [1000, 100, 10, 1]
    + [m, o, r, e] * [1000, 100, 10, 1]
    == [m, o, n, e, y] * [10000, 1000, 100, 10, 1]
)

To generat