> ## 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.

# Quickstart

> Compile your first Python program to C++ in under 5 minutes

Shed Skin compiles pure Python programs into optimized C++ code. This guide will walk you through compiling your first program.

## Before you begin

Make sure you have Shed Skin installed. If not, see the [installation guide](/installation).

<Note>
  Shed Skin works with a restricted subset of Python. Your program must be implicitly statically typed and cannot use dynamic features like `eval` or `getattr`.
</Note>

## Compile your first program

Let's compile the classic "Hello, World!" program and see Shed Skin in action.

<Steps>
  <Step title="Create a Python file">
    Create a file called `test.py` with the following content:

    ```python test.py theme={null}
    print('hello, world!')
    ```

    This simple program will help you verify that Shed Skin is working correctly.
  </Step>

  <Step title="Compile the program">
    Run the Shed Skin compiler on your Python file:

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      shedskin build test
      ```

      ```bash Windows theme={null}
      shedskin build --conan test
      ```
    </CodeGroup>

    This command translates your Python code to C++, then compiles it to a native binary. The `--conan` flag on Windows downloads required dependencies automatically.

    <Warning>
      On Windows, if you get an error about `nmake` not being found, open a "Visual Studio Developer Command Prompt" and try again.
    </Warning>

    You should see output indicating the translation and compilation process. When complete, you'll find the generated files in a `build` directory.
  </Step>

  <Step title="Run your compiled program">
    Execute the compiled binary:

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      build/test
      ```

      ```bash Windows theme={null}
      build\Debug\test.exe
      ```
    </CodeGroup>

    You should see:

    ```
    hello, world!
    ```

    Congratulations! You've successfully compiled and run your first Shed Skin program.
  </Step>
</Steps>

## Try a more complex example

Let's compile a program that does some real computation to see Shed Skin's performance benefits.

<Steps>
  <Step title="Create a computation-intensive program">
    Create a file called `mandelbrot.py`:

    ```python mandelbrot.py theme={null}
    import time

    def mandelbrot(max_iterations=1000):
        bailout = 16
        for y in range(-39, 39):
            line = []
            for x in range(-39, 39):
                cr = y/40 - 0.5
                ci = x/40
                zi = 0
                zr = 0
                i = 0
                while True:
                    i += 1
                    temp = zr * zi
                    zr2 = zr * zr
                    zi2 = zi * zi
                    zr = zr2 - zi2 + cr
                    zi = temp + temp + ci
                    if zi2 + zr2 > bailout:
                        line.append(" ")
                        break
                    if i > max_iterations:
                        line.append("#")
                        break
            print(''.join(line))

    t0 = time.time()
    mandelbrot()
    print('Time: %.2f seconds' % (time.time()-t0))
    ```

    This program renders a Mandelbrot fractal and measures execution time.
  </Step>

  <Step title="Compare performance">
    First, run it with Python:

    ```bash theme={null}
    python mandelbrot.py
    ```

    Note the execution time. Then compile and run it with Shed Skin:

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      shedskin build mandelbrot
      build/mandelbrot
      ```

      ```bash Windows theme={null}
      shedskin build --conan mandelbrot
      build\Debug\mandelbrot.exe
      ```
    </CodeGroup>

    The compiled version should be significantly faster - typically 10-100x speedup depending on your system.
  </Step>
</Steps>

## Build options

Shed Skin provides several options to optimize your compiled programs:

### Disable bounds checking

For maximum performance, disable array bounds checking:

```bash theme={null}
shedskin build --nobounds test
```

This can dramatically improve performance for indexing-heavy code, but be careful - invalid indices will cause crashes instead of raising `IndexError`.

### Integer and float precision

Control the size of numeric types:

```bash theme={null}
# Use 64-bit integers (default is 32-bit)
shedskin build --int64 test

# Use 64-bit floats (default)
shedskin build --float64 test
```

<Note>
  Use `--int64` if your program needs to handle integers larger than 2³¹-1.
</Note>

## Building extension modules

You can also compile Python code as extension modules that can be imported by regular Python programs.

Create `simple_module.py`:

```python simple_module.py theme={null}
def func1(x):
    return x + 1

def func2(n):
    d = dict([(i, i*i) for i in range(n)])
    return d

if __name__ == '__main__':
    print(func1(5))
    print(func2(10))
```

Compile as an extension module:

```bash theme={null}
shedskin build -e simple_module
```

Then use it from Python:

<CodeGroup>
  ```python Linux/macOS theme={null}
  # Change to build directory first
  import sys
  sys.path.insert(0, 'build')

  from simple_module import func1, func2

  print(func1(5))  # Output: 6
  print(func2(10)) # Output: {0: 0, 1: 1, 2: 4, ..., 9: 81}
  ```

  ```python Windows theme={null}
  # Change to build/Debug directory first
  import sys
  sys.path.insert(0, 'build/Debug')

  from simple_module import func1, func2

  print(func1(5))  # Output: 6
  print(func2(10)) # Output: {0: 0, 1: 1, 2: 4, ..., 9: 81}
  ```
</CodeGroup>

<Warning>
  Extension modules must call their own functions (directly or indirectly) to enable type inference. Place test calls under `if __name__ == '__main__'` so they don't run when imported.
</Warning>

## Next steps

Now that you've compiled your first programs, learn more about:

<CardGroup cols={2}>
  <Card title="Typing restrictions" icon="code" href="/concepts/typing-restrictions">
    Understand the static typing requirements
  </Card>

  <Card title="Python subset" icon="python" href="/concepts/python-subset">
    Learn which Python features are supported
  </Card>

  <Card title="Writing compatible code" icon="pen-to-square" href="/guides/writing-compatible-code">
    Best practices for Shed Skin programs
  </Card>

  <Card title="Optimization guide" icon="gauge-high" href="/guides/optimization">
    Get the best performance from your code
  </Card>
</CardGroup>

## Troubleshooting

### Compilation errors

If compilation fails, common issues include:

* **Dynamic typing**: Variables changing types between int and string
* **Mixed collections**: Lists containing different types like `[1, 'hello']`
* **Unsupported features**: Using `*args`, `**kwargs`, or nested functions

See the [troubleshooting guide](/resources/troubleshooting) for detailed solutions.

### Performance not as expected

* Use `--nobounds` to disable bounds checking
* Profile your code to find bottlenecks
* Reduce small object allocations (lists, tuples, class instances)
* See the [optimization guide](/guides/optimization) for more tips