Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/quantumlib/Stim/llms.txt

Use this file to discover all available pages before exploring further.

Stim ships in three forms: a Python package on PyPI (the most common way to use it), a standalone command-line binary, and a C++ library you can link into your own programs. The Python package is the recommended starting point for most users. The C++ library is useful when you need to embed Stim functionality directly in a C++ project, but be aware that the C++ API carries no backwards-compatibility guarantee.

​
Python package

The Python package is available on PyPI and can be installed with a single command. It requires Python 3.6 or later and automatically installs NumPy as a dependency. 
pip install stim
Verify the installation: 
import stim
print(stim.__version__)
Pin to a minor version (e.g. stim~=1.14) in production environments. Stim guarantees backwards compatibility of the Python API within a major version (1.X), but the exact behavior of random seeding is intentionally changed between minor versions — pin the version if reproducible seeds matter to you.

​
Command-line binary

The Stim CLI accepts commands such as stim sample -shots 100 -in circuit.stim. You can build it from source using CMake, Bazel, or GCC. 
# From the repository root:
cmake .
make stim

# Output binary ends up at:
#   ./out/stim

​
SIMD width

CMake lets you control vectorization via the -DSIMD_WIDTH flag:
FlagEffect
(omitted)Use the best option for the current machine (-march=native)
-DSIMD_WIDTH=256Force 256-bit AVX2 operations
-DSIMD_WIDTH=128Force 128-bit SSE2 operations
-DSIMD_WIDTH=64Disable SIMD entirely

​
C++ library

To embed Stim in a C++ project, build libstim and link against it. The recommended approach is CMake with FetchContent.
The C++ API makes no backwards-compatibility guarantees. It may change arbitrarily and without notice between minor versions. Always pin to a specific version tag, and prefer the Python API when backwards compatibility matters.
In your CMakeLists.txt, fetch Stim from GitHub and add libstim as a link dependency: 
include(FetchContent)
FetchContent_Declare(stim
    GIT_REPOSITORY https://github.com/quantumlib/stim.git
    GIT_TAG v1.14.0)   # Pin to the version you need
FetchContent_MakeAvailable(stim)

# For any target that needs Stim:
target_link_libraries(your_target PRIVATE libstim)
Then include Stim’s header in your source files: 
#include "stim.h"

stim::Circuit make_bell_pair_circuit() {
    return stim::Circuit(R"CIRCUIT(
        H 0
        CNOT 0 1
        M 0 1
        DETECTOR rec[-1] rec[-2]
    )CIRCUIT");
}

​
System requirements

ComponentRequirement
Python packagePython ≥ 3.6, NumPy (installed automatically)
C++ buildC++17-capable compiler (GCC, Clang, or MSVC); CMake or Bazel optional
SIMD accelerationAVX2 or SSE2 capable CPU (optional; falls back to scalar)

​
Versioning and compatibility

Stim’s Python package uses semantic versioning. Within a major version (1.X):
  • The Python API is backwards compatible, except for bug fixes, trap fixes, and spandrels.
  • The command-line API is backwards compatible under the same exceptions; a command will not stop working due to cleanup efforts alone.
  • The C++ API carries no compatibility guarantee and may change arbitrarily between minor versions.
Random seeding behavior is explicitly not stable between minor versions — the same seed may produce different results across versions. This is by design and enforced intentionally.
Stim is not an officially supported Google product. For questions, use the quantum computing Stack Exchange with the stim tag.

Build docs developers (and LLMs) love

Get started for freeTalk to us