Troubleshooting and FAQ

If you use GNU/Linux, look for Regina in your applications menu (for instance, the main GNOME or KDE menu). It might be classified under Science or Education. If all else fails, you can always start Regina from the command line by running regina-gui.

If you use macOS, you should have downloaded a drag-and-drop app bundle. You can start Regina simply by opening this app from wherever you dragged it to (typically the Applications folder).

If you use Windows, you can find Regina in the Start menu. Look for All Programs→Regina 7.4→Regina.

If you downloaded a GNU/Linux package, these tools should all be in /usr/bin/. You can run them directly from the command line:

    example$ regina-python
    Regina 7.4
    Software for low-dimensional topology
    Copyright (c) 1999-2025, The Regina development team
    >>>

If you downloaded a drag-and-drop app bundle for macOS, these tools are all shipped inside it. If you dragged Regina to the main Applications folder, you can find them in /Applications/Regina.app/Contents/MacOS/.

    example$ /Applications/Regina.app/Contents/MacOS/regina-python
    Regina 7.4
    Software for low-dimensional topology
    Copyright (c) 1999-2025, The Regina development team
    >>>

If you use Windows, the tool regina-python is not available. Windows. However, you can still use Python scripting in Regina's graphical user interface, by opening a graphical Python console or using script packets.

The other command-line tools (such as regfiledump, tricensus and so on) are installed under Windows beneath the Program Files directory; on some machines this directory is called Program Files (x86). Specifically, the command-line tools are stored in the subdirectory c:\Program Files\Regina\Regina 7.4\bin\.

    example$ "c:\Program Files\Regina\Regina 7.4\bin\tricensus.exe" -t2 output.rga
    Starting census generation...
    0:1 0:0 1:0 1:1 | 0:2 0:3 1:3 1:2
    0:1 0:0 1:0 1:1 | 0:2 0:3 bdry bdry
    ...

This means that whoever built your version of Regina did not include Python support in the build.

The best solution is to download a ready-made package from the Regina website. All of the ready-made packages should have Python support built in.

If you need to build Regina yourself from source, make sure you have the Python development files installed. If not, Regina will warn you about this when you run cmake:

example:~/source/regina/build> cmake ..
-- The C compiler identification is GNU
-- The CXX compiler identification is GNU
...
... (lots of output)
...
-----------------------------------------------------------------------------
-- The following OPTIONAL packages could NOT be located on your system.
-- Consider installing them to enable more features from this software.
-----------------------------------------------------------------------------
   * Python development  <http://www.python.org/>
     Build Python bindings for Regina

-----------------------------------------------------------------------------

-- Configuring done
-- Generating done
-- Build files have been written to: /Users/bab/source/regina/build
example:~/source/regina/build>

If you are stuck, please mail the authors for assistance, including your CMakeCache.txt if possible to help diagnose the problem.

At the time of writing, SnapPy is not compatible with multiple interpreters. If you run the graphical user interface and import the snappy module in more than one Python console, SnapPy will stop working.

A workaround is to open one console, import snappy within it, and then leave that console open. You can then use SnapPy in as many different consoles as you like: SnapPy will only break after you close that first console.

If you are not working directly with a data file, another option is to use the regina-python command-line tool. This only runs one instance of Python, and so avoids the problem.

The problem appears to be rooted in Cython, which SnapPy uses for its Python bindings. The SnapPy and Regina authors are currently working to find a suitable workaround.

If you can, it is best to install Regina from a ready-made package. See the Regina website for a list of GNU/Linux distributions that have packages available.

If you do need to build Regina yourself, the website offers help on building Regina from source. There is also a page on building Regina on different distributions, which suggests specific cmake options tailored to your particular type of machine.

Sometimes building an application on different hardware or against different versions of libraries can produce unforseen bugs that do not appear on the developer's machine(s). To help guard against such problems, Regina ships with a rich test suite. The test suite asks Regina to perform different calculations that isolate different portions of its mathematical code, and it verifies that Regina gets all the answers correct.

The test suite is split into several sections, including simpler Python and command-line utilities tests, as well as rich and detailed C++ calculation engine tests. The detailed C++ test suite is shipped with every full installation of Regina, whereas the other parts (Python and command-line utilities tests) are only available when building Regina from source.

If you have a full installation (e.g., you installed one of Regina's binary packages), then you can run the C++ test suite by typing regina-helper test. If you are building Regina from source, you can run all sections of the test suite (Python, utilities and C++ tests) by moving into your main build directory and typing make test ARGS=-V.

example:~/source/regina/build> make test ARGS=-V
Running tests...
...
... (some initial output)
...
1: Test command: /home/bab/git/regina/build/engine/testsuite/regina-testsuite
1: Test timeout computed to be: 10000000
1: [==========] Running 201 tests from 29 test suites.
1: [----------] Global test environment set-up.
1: [----------] 2 tests from AbelianGroupTest
1: [ RUN      ] AbelianGroupTest.incrementalBuild
1: [       OK ] AbelianGroupTest.incrementalBuild (0 ms)
1: [ RUN      ] AbelianGroupTest.tightEncoding
1: [       OK ] AbelianGroupTest.tightEncoding (0 ms)
1:
1: [----------] 6 tests from CoversTest
1: [ RUN      ] CoversTest.trivial
1: [       OK ] CoversTest.trivial (7 ms)
...
... (more output)
...
2: ----------------------------------------------
2: Test suite for Regina's command-line utilities
2: ----------------------------------------------
2:
2: Running censuslookup.test ... ok
2: Running regconcat.test (with filter) ... ok
...
... (more output)
...
3: ---------------------------------------
3: Test suite for Regina's python bindings
3: ---------------------------------------
3:
3: Running alltypes.test ... ok
3: Running angles.test ... ok
...
... (more output)
...
3: Regina calculation engine test suite
3:
3: AbelianGroupTest::incrementalBuild... ok.
3: AngleStructuresTest::empty... ok.
3: AngleStructuresTest::oneTet... ok.
...
... (lots and lots of output)
...
4: ----------------------------------------------------------------
4: Test suite for python bindings with a basic embedded interpreter
4: ----------------------------------------------------------------
4:
4: Running alltypes.test ... ok
4: Running angles.test ... ok
...
... (more output)
...
100% tests passed, 0 tests failed out of 4

Total Test time (real) =  171.41 sec
example:~/source/regina/build>

We see from the output above that Regina passed all of its tests (and hopefully this is what you will see too).

Perhaps something crashed. Maybe the program gave the wrong answer. Or it could be just a little too slow?

Please! - mail the authors and let us know. You are welcome to write to us directly (our email addresses are here). Or even better, use the GitHub issue tracking system so that the problem you report is publicly archived.

This program is permanently in development. There is a very long TODO list, and chances are your problem is on it. And then again chances are it's not. So please, let us know what you think can be fixed or improved.