Skip to main content

Documentation Index

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

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

​
General Questions

Shed Skin is a transpiler that converts implicitly statically typed Python programs to C++. The generated C++ code can be compiled into standalone executables or Python extension modules, offering significant performance improvements (typically 1-100x speedup, average 20x) over CPython.It uses type inference techniques to determine the implicit types in your Python code and generates the explicit type declarations needed for C++.
Shed Skin is experimental software still in active development (currently version 0.9.12). While it successfully compiles over 80 non-trivial programs, you may encounter bugs or limitations. It’s best suited for:
  • Performance-critical code sections (hundreds to thousands of lines)
  • Computational algorithms independent of external libraries
  • Projects where you can refactor code to fit Shed Skin’s constraints
Use with caution in production and thoroughly test compiled code.
Shed Skin is licensed under the GNU GPL version 3. See the LICENSE file in the repository for details.

​
Capabilities

For compatible code, typical speedups are:
  • Range: 1-100x faster than CPython 3.14
  • Average: 20x speedup
  • Median: 12x speedup
Performance varies significantly based on:
  • Code characteristics (computation vs. memory allocation heavy)
  • Compilation flags (--nobounds, --nowrap, optimization levels)
  • Algorithm complexity and data structures used
Shed Skin generally outperforms PyPy for computation-intensive code and is comparable to Numba in many cases.
No. Shed Skin only supports a restricted subset of Python with these key constraints:
  1. Static typing: Variables must have a single, consistent type
  2. Limited standard library: Only about 30 modules supported
  3. No dynamic features: No eval, getattr, isinstance, etc.
  4. Size limits: Best for programs under several thousand lines
  5. Feature restrictions: No nested functions, no *args/**kwargs, no multiple inheritance
See Python Subset Restrictions for complete details.
Yes, but with the extension module approach. You can:
  1. Identify performance bottlenecks in your code
  2. Extract them into separate modules
  3. Refactor these modules to be Shed Skin compatible
  4. Compile them as extension modules
  5. Import and use them in your main Python program
This allows you to accelerate critical sections while keeping your main codebase unchanged and able to use any Python libraries.
Yes, Shed Skin supports Python 3 syntax. However, it supports a restricted subset of Python 3 features. Not all Python 3.x features are available (e.g., match/case statements from 3.10+ are not supported).

​
Comparisons

PyPy is a JIT compiler that runs Python dynamically:
  • ✅ Supports full Python language and libraries
  • ✅ No code changes required
  • ❌ Slower startup time
  • ❌ Typically slower than Shed Skin for computational code
  • ❌ Requires using PyPy interpreter
Shed Skin is an ahead-of-time compiler:
  • ✅ Better performance for compatible code
  • ✅ Generates native binaries or CPython extensions
  • ✅ Works with standard CPython
  • ❌ Requires code to fit restricted subset
  • ❌ Limited library support
  • ❌ May require significant refactoring
Use PyPy for full compatibility, Shed Skin for maximum performance on compatible code.
Cython compiles Python-like code with optional type annotations:
  • ✅ Supports full Python language
  • ✅ Gradual optimization (add types as needed)
  • ✅ Excellent library support including NumPy
  • ❌ Requires manual type annotations for best performance
  • ❌ More verbose code
Shed Skin uses automatic type inference:
  • ✅ No type annotations needed (automatic inference)
  • ✅ Often better performance than non-annotated Cython
  • ✅ Cleaner code (pure Python)
  • ❌ More restrictive subset
  • ❌ Limited library support
Use Cython for flexibility and library support, Shed Skin when you want automatic optimization without annotations.
Numba JIT-compiles numerical Python code:
  • ✅ Excellent for NumPy-style array operations
  • ✅ Minimal code changes (decorator-based)
  • ✅ Supports GPU acceleration
  • ❌ Limited to numerical/array code
  • ❌ Slower for non-numerical code
  • ❌ Requires Numba runtime
Shed Skin compiles general Python code:
  • ✅ Good for general algorithms and data structures
  • ✅ Standalone binaries (no runtime)
  • ✅ Comparable or better performance for non-array code
  • ❌ No NumPy/GPU support
  • ❌ Requires full compilation step
Use Numba for array-heavy numerical code, Shed Skin for general algorithmic code.
Nuitka compiles full Python to C:
  • ✅ Supports complete Python language
  • ✅ All standard library modules
  • ✅ Compatible with all Python packages
  • ❌ Moderate speedups (typically 2-4x)
Shed Skin compiles restricted Python to C++:
  • ✅ Significant speedups (typically 10-20x+)
  • ❌ Restricted Python subset
  • ❌ Limited library support
Use Nuitka for compatibility, Shed Skin for maximum performance on compatible code.

​
Use Cases

Shed Skin is ideal when:
  • ✅ You have 100-5000 lines of computation-heavy code
  • ✅ Performance is critical (need 10-100x speedup)
  • ✅ Code can be isolated from external dependencies
  • ✅ You’re willing to refactor for compatibility
  • ✅ Your code uses basic Python features and data structures
  • ✅ You want to stay with pure Python syntax (no annotations)
Examples: algorithms, simulations, data processing, games, numerical computations.
Avoid Shed Skin when:
  • ❌ Code heavily uses unsupported libraries (pandas, requests, etc.)
  • ❌ Program is very large (>5000 lines)
  • ❌ You need dynamic Python features (eval, reflection, etc.)
  • ❌ Code uses many unsupported Python features
  • ❌ Performance is already acceptable
  • ❌ You can’t refactor existing code
In these cases, consider PyPy, Cython, Numba, or profile-guided optimization instead.
Not directly. Web frameworks (Django, Flask, FastAPI) are not supported. However, you could:
  1. Compile computational components as extension modules
  2. Import them into your web application
  3. Use them for performance-critical endpoints
Example: image processing, data analysis, or complex calculations in web API endpoints.
Partially. You cannot compile code that uses pandas, scikit-learn, or similar libraries. However, you can:
  1. Use Shed Skin for custom algorithms
  2. Pass data between NumPy/pandas and Shed Skin using .tolist() conversion
  3. Compile performance bottlenecks as extension modules
Note: Conversion overhead can be significant, so only worthwhile if substantial time is spent in the compiled code.

​
Technical Questions

Shed Skin analyzes your code to determine variable types automatically:
  1. Constraint generation: Analyzes operations to determine type constraints
  2. Iterative analysis: Propagates type information through the program
  3. Type resolution: Determines concrete types that satisfy all constraints
This is why all variables must have a consistent type - the inference system needs to resolve to a single static type for each variable.See Type Inference for technical details.
Shed Skin generates C++ code that requires:
  • Linux/macOS: g++ (GCC) or clang++
  • Windows: Microsoft Visual C++ (via Visual Studio Build Tools)
C++11 or later is required. Newer compilers generally produce faster code.
The Boehm garbage collector provides:
  • Automatic memory management (like Python)
  • Conservative garbage collection
  • Thread-safe operation
  • Good performance for C++ programs
This allows compiled code to allocate memory freely without manual management, maintaining Python’s memory semantics.
Yes, using the --nogc flag:
shedskin build --nogc myprogram
Pros: Slightly better performance, useful for memory profilingCons: Memory leaks, only use for short-running programs or when you manually manage memoryOnly recommended for benchmarking or specific use cases.
By default:
  • Integers: 32-bit signed (int32) on most platforms
  • Floats: 64-bit double precision (float64)
You can change this:
shedskin build --int64 myprogram     # 64-bit integers
shedskin build --int128 myprogram    # 128-bit integers  
shedskin build --float32 myprogram   # 32-bit floats
Integers and floats can usually be mixed (integers become floats).
Shed Skin currently has limited Unicode support:
  • Only 1-byte characters are fully supported
  • UTF-8 multi-byte characters may not work correctly
  • ASCII text works fine
For full Unicode support, keep string processing in pure Python and use Shed Skin for numerical/algorithmic code.

​
Extension Modules

Shed Skin extension modules are shared libraries (.so on Linux, .pyd on Windows) that CPython can import:
  1. Shed Skin compiles your Python code to C++
  2. The C++ code is compiled with Python C API bindings
  3. The resulting module can be imported like any Python module
  4. Data is converted between Python and C++ representations on call boundaries
See Extension Modules for details.
Supported types:
  • Scalars: int, float, complex, bool, str, bytes, bytearray
  • Containers: list, tuple, dict, set
  • Special: None, instances of user-defined classes
Not supported:
  • Functions/lambdas
  • Iterators/generators
  • Most standard library objects
Important: Builtin types are fully copied on each call/return. Changes to builtin objects don’t persist across boundaries.
No, this is currently not supported. Each extension module is independent. If you need modules to interact, keep the interaction logic in pure Python that imports both modules.

​
Development

  1. Test in CPython first: Run with python myprogram.py to catch logic errors
  2. Use assertions: They’re compiled unless you use --noassert
  3. Enable bounds checking: Don’t use --nobounds during development
  4. Use debug builds: Default Debug build type includes debugging symbols
  5. Use GDB/LLDB: Debug the compiled binary like any C++ program
  6. Print debugging: Good old print() statements work
See Debugging for more techniques.
Contributions are welcome! See Contributing for:
  • How to set up the development environment
  • Testing procedures
  • Code contribution guidelines
  • Adding library module support
  • Documentation improvements
Start with issues labeled “easytask” on GitHub.

​
Performance

Common reasons:
  1. Memory allocations: Creating many small objects (lists, tuples, class instances)
  2. Bounds checking: Enabled by default, use --nobounds after testing
  3. Suboptimal algorithm: Shed Skin doesn’t change your algorithm
  4. Mixed int/float operations: Can add conversion overhead
  5. Extension module overhead: Conversion of builtin types on each call
See Performance Tuning for optimization strategies.
For best performance:
shedskin build --nobounds --nowrap myprogram
  • --nobounds: Disable array bounds checking (test first!)
  • --nowrap: Disable wrap-around checking for negative indices
  • --int64: Use if you need large integers
  • --nogc: Only for short programs (causes memory leaks)
Also tune compiler flags in the FLAGS file for advanced optimization.
Shed Skin itself doesn’t provide parallelism features, but you can:
  1. Compile extension modules and use Python’s multiprocessing
  2. Use OpenMP in manually written C++ code integrated with Shed Skin
  3. Run multiple processes of the compiled binary
The Boehm GC is thread-safe, so multi-threaded C++ code is possible with manual integration.

Build docs developers (and LLMs) love

Get started for freeTalk to us