How to Set Up Python's Embeddable Distribution on Windows

Introduction

If there's something I appreciate about Windows as a Python developer, it's the ability to use the Python embeddable distribution.

The embedded distribution is a ZIP file containing a minimal Python environment. It is intended for acting as part of another application, rather than being directly accessed by end-users.

Think of it as a portable, ready-to-ship virtual environment. But, be aware of some limitations:

Third-party packages should be installed by the application installer alongside the embedded distribution. Using pip to manage dependencies is not supported, though with some care, pip may be included for automatic updates. Treat third-party packages as part of the application to ensure compatibility.

Though it might sound daunting, setting it up is straightforward. Follow these simple steps to have a fully functional embedded environment.

Get the Distribution

1. Visit Python's Windows Download Page.
2. Choose your preferred version and download the corresponding Windows x86-64 embeddable zip file.
3. Unzip the file.

For this tutorial, we'll assume you've downloaded Python 3.7 and unzipped it to C:\python\.

Install pip

The distribution doesn't have pip. Here's how to install it:

1. Download get-pip.py from the pip bootstrap website.
2. Save it to C:\python\get-pip.py.
3. In the command line, run C:\python\python get-pip.py.
4. Pip is now installed.

Configure Path

This distribution's runtime doesn't automatically include the current directory in sys.path. Fix it by:

1. Opening C:\python\python37._pth.

2. Uncommenting the line #import site and saving the file.

3. Creating a new file named C:\python\sitecustomize.py with the content:

   import sys
   sys.path.insert(0, '')
   

Addressing the lib2to3 Issue

You might encounter this error when installing packages:

error: [Errno 0] Error: 'lib2to3\Grammar3.6.5.final.0.pickle'

To fix it:

1. Unzip C:\python\python37.zip to a new folder.
2. Delete C:\python\python37.zip.
3. Rename the new folder to python37.zip.

Python's import system can treat zip files as folders but can't read pickle files inside zips, hence the change.

Running pip

If you prefer not to modify your PATH, use the command prompt:

1. CD C:\python\Scripts
2. pip install <package_name>

Running Scripts

To run scripts without changing your PATH:

1. Use C:\python\python <path to your script>

Conclusion

And that's it! You've successfully set up the Python embeddable distribution on Windows.