carefree-portable 📦️

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

💡We are planning to:

• use venv as a fallback solution for Linux / MacOS. (Done!)
• support other programming languages in the future, after Python is fully supported.

See Roadmap for more details.

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 / preset without much effort.
  • See the Stable Diffusion Web UI example on how we hijack the famous SD webui repo with a custom block and make it portable out-of-the-box.
• 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

Detailed usages can be found in the CLI & Configurations documentation.

Go to the root directory of your project first:

cd <path/to/your/project>

Generate Config

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.

Examples

• mixtral, which can generate a portable gradio demo for the famous Mixtral-8x7B LLM.
• Stable Diffusion Web UI, which can generate a portable version of the famous A1111 webui.
• Stable Diffusion - Playground v2, which can generate a portable version of the brilliant Playground v2 HuggingFace Space.
  • Playground v2 itself is a fantastic SD model. It is said that images generated by Playground v2 are favored 2.5 times more than those produced by SDXL. See their user study for more details.

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

5. 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!

Contributing

Contributions are truly welcomed!

See CONTRIBUTING.md for more details.

License

carefree-portable 📦️ is MIT licensed, as found in the LICENSE file.

---