build Command

Build Python modules to native executables or extension modules using CMake

The build command is the modern, recommended way to compile Python programs with Shed Skin. It uses CMake for build configuration and dependency management.

Syntax

shedskin build [options] <module.py>

Overview

The build command performs these steps:

1. Parse - Reads and validates your Python source code
2. Analyze - Performs type inference and static analysis
3. Generate - Creates C++ source files and CMakeLists.txt
4. Build - Compiles C++ code to native executable or extension module

Basic Examples

Build a standalone executable

shedskin build example.py

Output:

*** SHED SKIN Python-to-C++ Compiler 0.9.12 ***
Copyright 2005-2026 Mark Dufour and contributors; License GNU GPL version 3

>> reading Python
>> type inference
>> code generation
>> building with cmake

[prebuild time: 0.45 seconds]

The executable is created at build/example.

Build an extension module

shedskin build --extmod mymodule.py

This creates a .so (Linux), .dylib (macOS), or .pyd (Windows) file that can be imported from Python:

import mymodule  # Uses the compiled C++ extension

Build with optimization flags

shedskin build --nobounds --nowrap --build-type Release example.py

This disables safety checks and uses optimized compilation for maximum performance.

Output Directory Structure

After running build, your project will have:

project/
├── example.py           # Original Python source
├── example.cpp          # Generated C++ implementation  
├── example.hpp          # Generated C++ header
├── CMakeLists.txt       # Generated CMake configuration
└── build/               # CMake build directory
    ├── example          # Compiled executable
    ├── CMakeCache.txt
    ├── CMakeFiles/
    └── Makefile         # Generated by CMake

Command Options

Basic Options

name · string · required

Python file or module to compile (e.g., program.py)

-o, --outputdir · string

Specify output directory for generated C++ files (default: current directory)

-e, --extmod · boolean

Generate a Python extension module instead of a standalone executable

-x, --executable · boolean

Explicitly generate a standalone executable (this is the default)

-s, --silent · boolean

Silent mode - only show warnings, suppress informational output

-d, --debug · integer

Set debug logging level (1-3). Level 3 enables detailed type inference logging

Type Configuration

--int32 · boolean

Use 32-bit integers (default: platform-dependent)

--int64 · boolean

Use 64-bit integers

--int128 · boolean

Use 128-bit integers (not supported on Windows)

--float32 · boolean

Use 32-bit floating point numbers

--float64 · boolean

Use 64-bit floating point numbers (double precision)

Performance & Safety Options

-b, --nobounds · boolean

Disable array bounds checking for better performance

-w, --nowrap · boolean

Disable wrap-around checking for negative indices

--noassert · boolean

Disable assert statements in generated code

--nogc · boolean

Disable garbage collection (use with caution)

-t, --traceback · boolean

Print traceback for uncaught exceptions in compiled code

CMake Build Options

--generator · string

Specify CMake build system generator (e.g., “Ninja”, “Unix Makefiles”)

--jobs · integer

Build in parallel using N jobs (e.g., --jobs 4)

--build-type · string · default: "Debug"

Set CMake build type: Debug, Release, RelWithDebInfo, or MinSizeRel

--reset · boolean

Reset CMake build directory before building

--test · boolean

Run ctest after building

--ccache · boolean

Enable ccache for faster rebuilds

--target · string[]

Build only specified CMake targets (e.g., --target myprogram)

--nowarnings · boolean

Disable -Wall compilation warnings

Dependency Management

--local-deps · boolean · default: "true"

Build dependencies from bundled ext/ sources (default if no other option specified)

--spm · boolean

Install CMake dependencies using SPM package manager

--fetchcontent · boolean

Install CMake dependencies using FetchContent

Advanced Options

-I, --include-dirs · string[]

Add include directories for C++ compilation (can be specified multiple times)

-L, --link-dirs · string[]

Add library directories for linking (can be specified multiple times)

-l, --link-libs · string[]

Add libraries to link against (can be specified multiple times)

-X, --extra-lib · string

Add an extra builtins library directory

--collect-stats · boolean

Collect and report compilation statistics

Advanced Examples

Parallel build with release optimization

shedskin build --jobs 8 --build-type Release --nobounds myprogram.py

Build with custom output directory

shedskin build --outputdir ./generated myprogram.py

Generated C++ files go to ./generated/, executable goes to build/.

Build extension with 64-bit integers

shedskin build --extmod --int64 mymodule.py

Debug build with tracebacks

shedskin build --debug 2 --traceback --build-type Debug myprogram.py

Using Ninja generator for faster builds

shedskin build --generator Ninja --jobs 8 myprogram.py

Performance-optimized build

shedskin build \
  --build-type Release \
  --nobounds \
  --nowrap \
  --noassert \
  --ccache \
  --jobs $(nproc) \
  myprogram.py

Build vs Translate

Choose build when you want:

• Modern CMake-based workflow
• Better dependency management
• IDE integration (CMake support)
• Multi-configuration builds (Debug/Release)
• Cross-platform portability

Choose translate when you want:

• Simple Makefile-based builds
• Direct control over compilation
• Integration with existing Makefile workflows

Running the Compiled Program

After building, run your executable:

# Standalone executable
./build/myprogram

# Or use the run command to build and run in one step
shedskin run myprogram.py

For extension modules:

# The .so/.dylib/.pyd file must be in Python's import path
import mymodule
result = mymodule.some_function()

Troubleshooting

CMake not found

Shed Skin requires CMake 3.15 or later. Install it using:

# Ubuntu/Debian
sudo apt install cmake

# macOS
brew install cmake

# Windows
choco install cmake

Build directory issues

If you encounter CMake cache problems, reset the build:

shedskin build --reset myprogram.py

Slow builds

Speed up compilation:

shedskin build --ccache --jobs $(nproc) myprogram.py

See Also

• translate command - Traditional Makefile-based workflow
• CLI overview - All available commands
• Command-line options - Complete reference