Skip to main content

pycrossword - the Python Crossword Puzzle Generator and Editor

Project description

pycrossword - the Python Crossword Puzzle Generator and Editor

pycrossword is a pure-Python implementation of a crossword puzzle generator and editor.


pycrossword source code and documentation are hosted on Github

The python package is available from PyPi


  • full-fledged Qt 5 based GUI
  • cross-platform implementation
  • multilingual interface
  • fully Unicode-based
  • open, save, restore, export, and import crossword puzzles
  • powerful word sources: SQLite database / CSV (plaintext) / raw python list
  • unlimited undo / redo history
  • customizable word blacklisting
  • crossword generation (from word sources)
  • supports common puzzle file formats: XPF, IPUZ and raw text grid
  • easily load, edit and save word clues
  • flexible GUI settings: zoom, colors, fonts, grid settings, clues table look & feel, etc.
  • import & export configuration presets (JSON-based files)
  • auto app updating / new release checking from Github / PyPI
  • lookup word definition in an online dictionary and Google
  • manual editing of individual words and suggestions from word sources
  • comfortable navigation in GUI (hotkeys, keystrokes, mouse)
  • multi-character editing
  • extensive grid editing (row / column / cell manipulation, block duplication etc.)
  • context menus
  • hi-res printing to PDF or printer with customizable page / element layout
  • export crossword to image (jpg, png, tiff) / PDF / SVG with customizable resolution and other settings
  • store crosswords in cloud and share them in social networks (Twitter, Facebook, Instagram etc.)
  • view user-friendly stats on current crossword in chart
  • inbuilt web browser and Python code editor
  • app extension through external and custom plugins (Python API included)
  • comprehensive Doxygen-generated API reference and rich help documentation



You must have the following applications / packages installed in your system:

  • Python 3.7+ (the app was written and tested with Python 3.7.4 and 3.8.0)
  • Python packages:
    • pip
    • PyQt5>=5.14
    • QScintilla>=2.11
    • jedi>=0.16
    • yapsy>=1.12
    • requests
    • numpy
    • pandas
    • altair
  • Git (should be pre-installed on most modern Linux and Mac systems, alternatively install from the git website)

The latter two (packages and Git) are not actually required if you opt for the PyPi (pip) installation variant as described below.

Installation options

Choose one of the two installation options.

1. Clone repo - copy entire source code with version control history

To get the latest (non-stable) version, run:

git clone .

This will checkout to the master branch which tracks all recent changes, some of which may not be yet merged into a release version.

To get the latest stable version, run:

git clone .
git reset --hard latest

This will checkout to the branch pointed at by the latest tag which will always be the latest stable release.

Install the required packages

I recommend (as many do) installing packages into python's virtual environment using virtualenv or the inbuilt venv:

Create a new virtual environment:

Linux / Mac

cd myprojects
venv pycross
cd pycross
. ./bin/activate


cd myprojects
venv pycross
cd pycross

This step is, of course, optional. You can skip it if you don't want to use virtual environments for some reason or other.

Then just run:

cd crossword
python -m pip install -r requirements.txt

If you're using a virtual environment, you can deactivate it after closing the app with deactivate.

2. Install from PyPi

Create your virtual environment as described above (which is again optional). Then use pip to download and install pycrossword (together with the required additional packages):

pip install --upgrade pycrossword


Run pycross on Linux/Mac or pycross.bat on Windows to launch the pycrossword UI app. This should work both with and without the Python virtual environment.

To launch the app manually, run

python [optional command-line params]

from your pycross/ directory.

The command-line parameters that can be passed to are as follows:

  • -s or --settings + "path to *.pxjson settings file": load app from a preset (configuration file)
  • -o or --open + "path to crossword file": open a crossword file (*.xpf or *.ipuz)
  • -n or --new: create a new crossword on startup (see creation parameters below)
  • --cols: number of columns in the new crossword (default = 15)
  • --rows: number of rows in the new crossword (default = 15)
  • --pattern: pattern number for the new crossword (one of 1...6, default = 1)
  • -e or --empty: don't open or create a crossword
  • -a or --addsrc + "{source data}": add a word source (see for description of the source data structure)

Alternativaly, you can register the pycrossword file associations at initial run (go to Settings > Common > Register file associations). After that, you can launch the app by double-clicking crossword files (like *.xpf or *.ipuz) or settings files (*.pxjson)

See User Guide for detailed usage.


See roadmap.txt for future plans!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pycrossword- (15.2 MB view hashes)

Uploaded Source

Built Distribution

pycrossword- (16.2 MB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page