InChI - The IUPAC International Chemical Identifier

InChI is a structure-based chemical identifier, developed by IUPAC and the InChI Trust. It is a standard identifier for chemical databases that facilitates effective information management across chemistry.

InChI and InChIKey are open standards. They use unique machine readable strings to represent, store and search chemical structures. All the software and algorithms related to them are open source.

Contents of this document

Click on the icon in the upper right of this README to view the table of content.

What is InChI

InChI is a structure-based textual identifier, strictly unique, non-proprietary, open source, and freely accessible.

InChI identifiers describe chemical substances in terms of layers of information – the atoms and their bond connectivity, tautomeric information, isotope information, stereochemistry, and electronic charge.

With its fixed length of 27 characters the InChIKey — the hashed version of the InChI — allows for a compact representation and usage in databases or search engines.

InChI is used by most of the large chemical databases and software applications handling many millions of chemical structures.

InChI enables the linking and interlinking of chemistry and chemical structures on the web and computer platforms. By enhancing the discoverability of chemical structures, InChI advances the FAIR Guiding Principles for scientific data management and stewardship. FAIR was published in 2016 to provide guidelines to improve the Findability, Accessibility, Interoperability, and Reuse of digital assets. InChI provides ‘Findability’ for chemical structures and extends Interoperability between platforms, both of which foster Accessibility and Reuse.

InChI Trust

The InChI Trust is a charity that supports the development and promotion of the InChI standard. It works in partnership with IUPAC to update and release new extensions to and applications of InChI. The Trust is a membership organisation, governed by its Board of Trustees which includes representation from IUPAC.

The scientific design of the various tools and capabilities that comprise the InChI code are defined by the InChI Working Groups which are made up of volunteers from the InChI community with IUPAC oversight. These voluntary groups are each focused on specific areas of chemistry or tools within the InChI code. See Working Groups for details on each group and their membership.

The development of the code is coordinated by the Technical Director of the InChI Trust, together with the working groups, IUPAC and our development partners. Our development partners currently include RWTH Aachen (as part of NFDI4Chem, acknowledging funding from Volkswagen Stiftung and the Data Literacy Alliance – DALIA), and the Beilstein Institut.

How to contribute

Should you have any questions, comments, or suggestions, please feel free to post them here: GitHub discussion page.

If you encounter a bug, we kindly request you to create an issue.

You are welcome to contribute to this project. To do so, you may submit a pull request:

Source code documentation

We've started documenting the source code with Doxygen.

Follow the Doxygen syntax when writing comments. For example

/**
* @brief Read a field from a MOL file.
*
* @param data Pointer to the destination buffer.
* @param field_len Length of the field to read.
* @param data_type Type of the data to read.
* @param line_ptr Pointer to a variable that will receive the address of the next line.
* @return for MOL_FMT_STRING_DATA: number of bytes excluding trailing zero
*         for all others:  1=success; 0 = empty; -1= error
*/
int MolfileReadField(void *data,
     int field_len,
     int data_type,
     char **line_ptr);

The Doxygen documentation syntax is quite powerful: you can include formulas, tables, and diagrams. For details see https://www.doxygen.nl/manual.

The documentation is built on every push to the default branch of this repository and hosted at https://iupac-inchi.github.io/InChI/. That is, your comments will automatically be rendered to HTML and served as online documentation.

Contents of this repository

INCHI-1-BIN

The INCHI-1-BIN subfolder contains binaries of the command line InChI executable (inchi-1) and the InChI API library (libinchi).

INCHI-1-DOC

The INCHI-1-DOC subfolder contains documentation related to the InChI Software.

INCHI-1-SRC

The INCHI-1-SRC subfolder contains the InChI source code. It also contains examples of InChI API usage, for C (inchi_main, mol2inchi, test_ixa), as well as the InChI API library source code and related projects/makefiles.

INCHI-1-TEST

The INCHI-1-TEST subfolder contains the test scripts and resources.

Using precompiled binaries/libraries

64-bit and 32-bit precompiled binaries/libraries (i.e. executable, .dll/.so/.dylib and ELF files) are located in the following folders:

Microsoft Windows
Files (given in compressed .zip format)	Location(s)	Compiler
inchi-1.exe	64-bit: INCHI-1-BIN/windows/64bit	Microsoft Visual Studio C++ (MSVC)
	32-bit: INCHI-1-BIN/windows/32bit	MinGW-w64/Clang(1)
libinchi.dll + corresponding inchi_main.exe	64-bit: INCHI-1-BIN/windows/64bit/dll	Microsoft Visual Studio C++ (MSVC)
	32-bit: INCHI-1-BIN/windows/32bit/dll	MinGW-w64/Clang(1)

Table pcb01. Location of precompiled binaries/libraries for Microsoft Windows platforms.

UNIX-based OSs (except Apple macOS)
Files (given in compressed .zip format)	Location(s)	Compiler
inchi-1 (ELF file)	64-bit: INCHI-1-BIN/linux/64bit	GCC
	32-bit: INCHI-1-BIN/linux/32bit	Clang/LLVM(2)
libinchi.so/libinchi.dylib + corresponding inchi_main (ELF file)	64-bit: INCHI-1-BIN/linux/64bit/so	GCC
	32-bit: INCHI-1-BIN/linux/32bit/so	Clang/LLVM(2)

Table pcb02. Location of precompiled binaries/libraries for Linux/Apple macOS platforms.

⁽¹⁾ IMPORTANT NOTE: Since 32-bit binaries for Microsoft Windows operating system have been compiled using MinGW-w64, it has been reported that in certain environments a dynamic link library libgcc_s_dw2-1.dll has to be included in the same folder with the executables. Therefore, libgcc_s_dw2-1.dll has been added to INCHI-1-BIN/windows/32bit and INCHI-1-BIN/windows/32bit/dll folders (we would like to thank nbehrnd for his assistance with this matter).

⁽²⁾ In order to make makefile32s more consistent on all operating systems (see preceding note ⁽¹⁾), and for easier change of the default compiler, the default compiler on 32-bit UNIX-based OSs has been set to Clang/LLVM.

Precompiled binaries for Apple macOS (i.e. .app executables and .dylib libraries) will be provided soon. Until then, please note that InChI can now be compiled from source on Apple macOS using native/default Clang or GCC (if installed).

Building from source

Users can build any InChI subproject (e.g. InChI CLI/inchi-1, libinchi, etc.) from source using:

• CMake build system (Microsoft Windows, Apple macOS, Linux, FreeBSD, OpenBSD, Solaris, AIX)
• Microsoft Visual Studio projects (Microsoft Windows)
• Make build system (Microsoft Windows, Unix, Apple macOS)

CMake build system

To build InChI sub-projects from source using CMake build system, make sure that CMake is installed on your system. Users can choose between running interactive CMake build tool script and running CMake in Command Line Interface (CLI).

Interactive CMake build tool

The easiest way to build any (or all) InChI sub-project(s) using CMake is to run the CMake build tool (cmake_build_tool.bat for Microsoft Windows platforms or cmake_build_tool.sh for Linux/Apple macOS platforms) which is located in the INCHI-1-SRC directory.

• Microsoft Windows

  • Double click on batch file cmake_build_tool.bat.
  • Run cmake_build_tool.bat command in Command Prompt.
  • Run ./cmake_build_tool.bat command in PowerShell.

• Linux/Apple macOS

  • Run ./inchi_build_tool.sh within INCHI-1-SRC directory.

CMake build tool users are only required to enter a number that corresponds to one or all InChI sub-projects which should be built from source using CMake.

Figure cmbt01. CMake build tool: start menu

Figure cmbt02. CMake build tool: build success

Please note that the main build directory CMake_build is positioned one level up relative to the directory INCHI-1-SRC.

Using CMake with command line interface (CLI)

Command line interface is recommended for gaining more control over the CMake build process. Please note that in CMake terminology a directory in which all project binaries/libraries are built is called build directory, whilst a directory in which project's CMakeLists.txt script is contained is called source directory.

Each InChI sub-project has a dedicated CMakeLists.txt file in its corresponding source directory:

InChIsubproject	Source directory containing CMakeLists.txt script
InChI CLI (inchi-1)	INCHI-1-SRC/INCHI_EXE/inchi-1/src
libinchi	INCHI-1-SRC/INCHI_API/libinchi/src
InChI API (inchi_main)	INCHI-1-SRC/INCHI_API/demos/inchi_main/src
Mol2InChI	INCHI-1-SRC/INCHI_API/demos/mol2inchi/src
Test IXA (test_ixa)	INCHI-1-SRC/INCHI_API/demos/test_ixa/src

Table sdl01. CMake source directories for all InChI sub-projects.

Building any C++/C project with CMake consists of two parts:

• Configuration process
• Build process based on files created in configuration process

CMake configuration process is usually started in two ways:

• By running the following set of commands:

  mkdir <build_directory>
  cd <build_directory>
  cmake <source_directory>
  

• By running the following command:

  cmake -B <build_directory> -S <source_directory>
  

  • Please note that it is highly recommended to specify <source_directory> if this command is used, as CMake executable might report an error if project's CMakeLists.txt has not been found; for example:
    • cmake -B <build_directory> will work if the current directory is the <source_directory>, i.e. contains CMakeLists.txt
    • cmake -S <source_directory> will build all the binaries/libraries in the current directory
  • If <build_directory> does not exist, it will be created by CMake (on condition that CMakeLists.txt has been found)

In case of building a InChI sub-project, the name of <build_directory> can be arbitrary, whereas <source_directory> must be selected from Table sdl01.

Some important notes regarding CMake configuration:

• CMake automatically detects a default C++/C compiler or a compiler specified in CMakeLists.txt. Compiler can be explicitly specified using additional options provided by CMake executable, e.g. -DCMAKE_C_COMPILER=<name_of_C_compiler> and/or -DCMAKE_CXX_COMPILER=<name_of_C++_compiler>; these additional options can be combined (please refer to section Examples of building InChI sub-projects using CMake with CLI below).
• In case where multiple types of C++/C build systems are present, a specific build system can be selected using CMake generators, which enable CMake to write the input files for a specified native build system. CMake generators can be specified with the CMake executable option: -G <name_of_cmake_generator>.
• If single configuration generators are used (e.g. Makefile Generators, Ninja, etc.), the build configuration should be specified at configure time using CMAKE_BUILD_TYPE variable, i.e. -DCMAKE_BUILD_TYPE=<build_type> configuration option. CMAKE_BUILD_TYPE variable can have four different values:
  • Debug
  • Release
  • RelWithDebInfo
  • MinSizeRel.
• Conversely, build configuration for multi-configuration generators (e.g. Visual Studio, XCode, Ninja Multi-Config, etc.) is selected at build time (please refer to section CMake build process below).

CMake build process can start after configuration has been completed successfully by running the following command:

cmake --build <build_directory>

• Build configuration for multi-configuration generators (e.g. Microsoft Visual Studio, XCode, Ninja Multi-Config, etc.) can be set at build time using the CMAKE_CONFIGURATION_TYPES variable. CMAKE_CONFIGURATION_TYPES variable should contain a subset of the four build type values (Debug, Release, RelWithDebInfo and MinSizeRel).
• CMAKE_CONFIGURATION_TYPES can be overridden by the project or a user; a typical example is --config <build_type> option for Microsoft Visual Studio generator.
• If Microsoft Visual Studio generator is used, a target project can optionally be specified at build time using --target <target_project> option.
• As with CMake configuration options, CMake build options can also be combined (please refer to section Examples of building InChI sub-projects using CMake with CLI below).

Please note that CMake configuration files and all build artefacts (binaries/libraries) are placed in <build_directory>.

Examples of building InChI sub-projects using CMake with CLI

• Building main InChI API sub-project using default options for configuration and build:

# current folder is one level above INCHI-1-SRC root
# 'cmake_build' can be replaced with any directory name
cmake -B cmake_build -S INCHI-1-SRC/INCHI_API/demos/inchi_main/src
cmake --build cmake_build

• Building InChI CLI (inchi-1) sub-project using Microsoft Visual Studio generator for 64-bit platorms, targeting ALL_BUILD project with Release build configuration:

# current folder is INCHI-1-SRC root
# 'cmake_bin/vs2022' can be replaced with any directory name
mkdir ../cmake_bin/vs2022 # cmake_bin directory will be located outside INCHI-1-SRC
cd ../cmake_bin/vs2022
cmake -G "Visual Studio 17 2022" -A x64 ../../INCHI-1-SRC/INCHI_EXE/inchi-1/src
cmake --build cmake_bin/vs2022 --target ALL_BUILD --config Release  # option '--target ALL_BUILD' can be omitted (default)

• Building InChI CLI (inchi-1) sub-project using (single configuration) Ninja generator, with Release build configuration and Clang compiler:

# current folder is one level above INCHI-1-SRC root
mkdir cmake_build
cd cmake_build # 'cmake_build' can be replaced with any directory name
cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ../INCHI-1-SRC/INCHI_EXE/inchi-1/src
cmake --build .

Microsoft Visual Studio projects

On Microsoft Windows, solution/project files for Microsoft Visual C++ (MSVC)/Clang/LLVM and Intel oneAPI DPC++/C++ Compiler are provided for all InChI sub-projects. The solution/project files are located in the following directories:

• INCHI-1-SRC/INCHI_EXE/inchi-1/vc14 (command line/CLI/inchi-1 version)
• INCHI-1-SRC/INCHI_API/libinchi/vc14 (API version consisting only of libinchi.dll)
• INCHI-1-SRC/INCHI_API/demos/inchi_main/vc14 (API version consisting of libinchi.dll and its corresponding executable inchi_main.exe)
• INCHI-1-SRC/INCHI_API/demos/mol2inchi/vc14 (API version consisting of libinchi.dll and its corresponding executable mol2inchi.exe)
• INCHI-1-SRC/INCHI_API/demos/test_ixa/vc14 (API version consisting of libinchi.dll and its corresponding executable test_ixa.exe)

Make build system

On UNIX-based OSs/Apple macOS/Microsoft Windows, InChI sub-projects can be compiled from the source using Make software if GCC and Clang/LLVM compilers are installed. makefile/makefile32 files are provided in the following directories:

• INCHI-1-SRC/INCHI_EXE/inchi-1/gcc (command line/CLI/inchi-1 version)
• INCHI-1-SRC/INCHI_API/libinchi/gcc (API version consisting only of libinchi.dll/libinchi.so/libinchi.dylib)
• INCHI-1-SRC/INCHI_API/demos/inchi_main/gcc (API version consisting of libinchi.dll/libinchi.so/libinchi.dylib and its corresponding executable/ELF inchi_main.exe/inchi_main)
• INCHI-1-SRC/INCHI_API/demos/mol2inchi/gcc (API version consisting of libinchi.dll/libinchi.so/libinchi.dylib and its corresponding executable/ELF mol2inchi.exe/mol2inchi)
• INCHI-1-SRC/INCHI_API/demos/test_ixa/gcc (API version consisting of libinchi.dll/libinchi.so/libinchi.dylib and its corresponding executable/ELF test_ixa.exe/test_ixa)

New features in makefile/makefile32:

• makefile/makefile32 files are configured to detect OSs automatically, so it is no longer needed to specify OS explicitly or run batch/bash script(s) before compiling.
• GCC and Clang/LLVM compilers are also automatically detected by makefile/makefile32 files with:
  • GCC set as a default compiler on 64-bit platforms.
  • Clang/LLVM set as a default compiler on 32-bit platforms (please refer to these notes for more details).
• If both GCC and Clang/LLVM compilers are installed, setting a default compiler can be done simply by changing the CCN parameter in makefile/makefile32 where:
  • CCN = 1 corresponds to GCC.
  • CCN = 2 corresponds to Clang/LLVM.

Support for native/default Apple macOS Clang compiler is now provided with 64-bit versions of makefile files (thanks to John Mayfield for his assistance with this matter).

If makefile/makefile32 is used for compiling libinchi on Microsoft Windows, libinchi.dll is now generated instead of libinchi.so. Also. please make sure to read the notes regarding the required libgcc_s_dw2-1.dll for running 32-bit executables on Microsoft Windows operating system in certain environments.

Additional notes

Intel oneAPI DPC++/C++ compiler support has been provided since InChI v.1.07.2. Please note that the support will not be provided for Intel C++ Compiler Classic (icc) as it has been discontinued since oneAPI 2024.0 release.

Known issues

If main API sub-project (i.e. libinchi.so and inchi_main ELF file) is built using Make software and Clang/LLVM compiler on Linux OS, and libinchi.so cannot be found by inchi_main, LD_LIBRARY_PATH should be set either temporarily or permanently before inchi_main ELF file is used. It might be worth trying to change the value of LINKER_CWD_PATH to -Wl,-R,"",-rpath,$(LIB_DIR) (i.e. replacing = with ,) in corresponding makefile/makefile32; however, please note that during our tests, this option failed to generate libinchi.so with Clang/LLVM on Linux. More reliably, LD_LIBRARY_PATH can be set in several ways:

• Temporarily

  • Run ldlp_fix.sh script (located in /INCHI_API/bin/linux) with either of the following CLI commands:
    • ./ldlp_fix.sh
    • source ldlp_fix.sh.
  • Please note tha the path to libinchi.so can be edited in ldlp_fix.sh. Alternatively, run export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libinchi.so.

• Permanently

  • Add the following line in ~/.bashrc:
    • LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/path/to/libinchi.so".
  • Alternatively, add the libinchi.so path to ld.so.conf, which means adding a file /etc/ld.so.conf.d/local.conf containing <path/to/>libinchi.so and then running sudo ldconfig.
  • Another alternative is to use the open-source utility patchelf.

If a similar issue occurs on Apple macOS, one of the above solutions should be applied for setting DYLD_LIBRARY_PATH and/or DYLD_FALLBACK_LIBRARY_PATH (which behave like LD_LIBRARY_PATH).

Important note about pre-C99 C language standard support

Pre-C99 C language standard support will be gradually phased out starting with InChI version 1.07.5. Please make sure that the following versions of C compilers are installed:

• GCC 4.5 or later
• LLVM/Clang 8.0 or later
• Microsoft Visual C++ 12.0/Microsoft Visual Studio 2013 or later

Optional features

Bounds checking functions

To further improve code security, bounds checking functions (see Annex K of C11 standard) can be optionally used starting from InChI version v.1.07.0. Since a number of C compilers (e.g. GNU GCC) do not support bounds checking functions, they can be installed using some of the third-party open-source libraries such as:

• safec libc extension with all C11 Annex K functions -- actively maintained
• Safe C lib
• Implementation of C11 Annex K "Bounds-checking interfaces" ISO/IEC 9899:2011

The use of bounds checking functions in InChI can be enabled/disabled in bcf_s.h.

Intel oneAPI Threading Building Blocks (oneTBB)

If you wish to use Intel oneAPI Threading Building Blocks (oneTBB), please follow the instructions given in header files mode.h and tbbmalloc_proxy.h. Please note that the pre-compiled binaries do not use oneTBB.

Experimental features under development

Some of the experimental/engineering/hidden options featured in InChI 1.07 which are known to be not fully functional are:

Command line

32-bit Microsoft Visual Studio C++ (MSVC) Win32 and Microsoft LLVM/Clang compiler-specific issues with the following options:

• AMI Allow multiple input files (wildcards supported)
• AMIOutStd Write output to stdout (in AMI mode)
• AMILogStd Write log to stderr (in AMI mode)
• AMIPrbNone Suppress creation of problem files (in AMI mode)

API (.dll/.so/.dylib)

• KET Consider keto-enol tautomerism (experimental)
• 15T Consider 1,5-tautomerism (experimental)
• PT_06_00 Consider 1,3 heteroatom shift (experimental)
• PT_13_00 Consider keten-ynol exchange (experimental)
• PT_16_00 Consider nitroso-oxime tautomerism (experimental)
• PT_18_00 Consider cyanic/iso-cyanic acids (experimental)
• PT_22_00 Consider imine/amine tautomerism (experimental)
• PT_39_00 Consider nitrone/azoxy or Behrend rearrangement (experimental)
• Polymers105 Allow processing of polymers (experimental, legacy mode of v. 1.05)
• NoEdits Disable polymer CRU frame shift and folding
• NPZz Allow non-polymer-related Zz atoms (pseudo element placeholders)
• SAtZz Allow stereo at atoms connected to Zz (default: disabled)
• InChI2StructTest mode: Mol/SDfile -> InChI -> Structure -> (InChI+AuxInfo) -- produces Fatal Error (2)3 just like in InChI v.1.06
• InChI2InChI Convert InChI string(s) into InChI string(s) -- produces Fatal Error(2)3 just like in InChI v.1.06

Please refrain from using the above mentioned options as they might not function properly, or will not be recognized. Regular updates with regard to their functionality will be posted on this page.