Skip to main content

Introduction

carefree-portable 📦️ aims to help you create portable (Python 🐍) projects of your codes / repo!

AI PC​

AI PC is a 'new' concept that Intel proposed (see here). Since AI PC users often have zero knowledge about programming, it is important to provide them with a portable version of the AI project. This is where carefree-portable 📦️ comes in handy!

Highlights​

  • Portable: The generated portable project can be used directly without any extra requirements.
    • For example, you can run a portable Python project even without Python installed!
  • Extensible: You can easily extend the functionality of carefree-portable 📦️ by editing existing configurations, or adding brand new Block / presets without much effort.
  • Integrable: You can integrate carefree-portable 📦️ with (GitHub) CI to automatically generate a portable version of your project.
    • Basically, you only need to create a cfport.json file in the root directory of your project, and then run cfport package in your CI workflow (see Usages for more details).
    • Here's an example of how carefree-portable 📦️ packages itself into a portable version in the GitHub CI workflow.

Installation​

carefree-portable 📦️ requires Python 3.8 or higher.

pip install carefree-portable

or

git clone https://github.com/carefree0910/carefree-portable.git
cd carefree-portable
pip install -e .

Usages​

info

Detailed usages can be found in the CLI section.

Go to the root directory of your project first:

cd <path/to/your/project>

Generate Config​

User Guides

To generate a default config, run:

cfport config

This command will genearte a cfport.json file in the current directory. To make it work properly, you may need to edit the python_requirements field, which is a list of Python packages that your project depends on.

  • Don't forget to add your own project to this field as well!

Packaging​

After generating the config, you can package your project by running:

cfport package

PyTorch​

Since nowadays many fancy projects are built on top of pytorch, we provided a preset config for pytorch projects, which can be generated by:

cfport config --preset torch-2.1.0-cu118
# or
cfport config --preset torch-2.1.0-cpu

This will generate a cfport.json with a pre-defined requirement in the python_requirements field.

You may notice that the pre-defined requirement starts with $pip instead of pip. This is important because it can tell carefree-portable 📦️ to use the correct pip executable when packaging your project.

Portable carefree-portable 📦️​

You may also download the carefree-portable-*.zip from the assets of the latest Releases. The zip files contain the portable versions of carefree-portable 📦️ that can be used directly:

  • On Linux / MacOS, you still need to have Python installed (to activate the venv), but no extra packages are required.
  • On Windows, you can even run it without Python installed!

If you are using this portable version, just make sure to:

  • cd into the unzipped carefree-portable-* folder.
  • Replace cfport with .\run.bat (Windows) / bash run.sh (Linux / MacOS) in the following commands.
  • Replace python with <path\to\portable\python> in other python commands. The portable python locates at:
    • Windows: .\carefree-portable-*\python_embeddables\python-3.10.11-embed-amd64\python.
    • Linux / MacOS: ./carefree-portable-*/python_venv/bin/python3.

Here's a step by step guide on how to use the portable carefree-portable 📦️ to run the Stable Diffusion Web UI example:

  1. Download the carefree-portable-*.zip from the assets of the latest Releases.
  2. Unzip the carefree-portable-*.zip to a folder (let's say, ./carefree-portable-*), and cd into it.
  3. Download the run.py from here, and put it into the unzipped folder (./carefree-portable-*).
  4. Run the following command, and wait until the webui pops up:
.\python_embeddables\python-3.10.11-embed-amd64\python run.py
  1. After these steps, you'll obtain a portable version of the SD webui (locates at ./carefree-portable-*/sd_webui_cfport), which can be used directly without any extra requirements!
Last updated on