Add python project config via uv while keeping backward compatibility with pip install method

[bmaltais]

As I started work on the GUI I need to be able to properly use the tuner code as a python module. For this purpose I am proposing to add support to uv as the python environment and module management solution.

It will also retain backward compatibility with the manual way of installing the requirements.

If you want to try uv instead, just install uv as per then installation instructions as found in the README.md and then simply use the uv run ... version of the commands. It will install the required python version, create the .venv and install all required modules on 1st run.

[FurkanGozukara]

it is amazing you started to work on gui for this :D i would do a terrible one thank you so much @bmaltais and @kohya-ss

[bmaltais]

@FurkanGozukara You can always contribute README sections about how to configure the GUI for best results, etc, etc. If everyone contribute a little something then the progress goes faster.

For example, validating that the instructions on how to install the app up to the point where you can run uv run gui.py would be great. I only tested on Windows... but might be worth testing on other platform.

[bmaltais]

I have added a super basic GUI consisting of the accelerate launch parameters and one feild to type the custom parameters... but this will allow you to train ;-)

Now that this work, I can focus on the config load and save part so the user inputs can be saved to a config file

When that is done, I will start to add individual feilds for the cli options.

[bmaltais]

OK, you can now save and load config to toml file. This also allow to start the GUI with a specific toml config file and get all the feilds populated with the values.

This should also allow me to run the cli by feeding it the toml with the saved values and everything should run.

@kohya-ss is the syntax to pass parameters as toml the same as sd-scripts?

[kohya-ss]

Thank you for your continuous efforts.
I don't personally use uv, but I understand its benefits. If backwards compatibility can be ensured, such as by installing with pip, I would definitely like to introduce it.

I have a few questions.

First, it's a PyTorch and CUDA version issue. I think we need to stick sometimes to CUDA <12.4 or 11.x in some environments. Similarly, we may want to change the version of PyTorch (because tuner will work with 2.4.x, and for example, when cloud environment comes with 2.4 pre-installed). How can we address this issue with uv and pyproject.toml?

Also, I would like to make this project compatible with Python 3.9 to 3.12 if possible. Is that possible with uv?

[kohya-ss]

@bmaltais

@kohya-ss is the syntax to pass parameters as toml the same as sd-scripts?

It's same as sd-scripts. If not work, please let me know :)

[bmaltais]

@kohya-ss I tried to pass a toml with the config and it gives an error:

hv_train_network.py: error: the following arguments are required: --dataset_config, --dit, --output_name

I am calling it with:

accelerate launch --dynamo_backend no --dynamo_mode default --mixed_precision bf16 --num_processes 1 --num_machines 1 --num_cpu_threads_per_process 2 D:/musubi-tuner-gui/musubi-tuner/hv_train_network.py --config_file ./test/output/name-of-lora_20250118-211157.toml

And my toml file contain:

dataset_config = "./test/config/dataset.toml"
discrete_flow_shift = 7
dit = "C:/Users/berna/Downloads/mp_rank_00_model_states_fp8.safetensors"
dit_dtype = "bfloat16"
fp8_base = true
gradient_accumulation_steps = 1
gradient_checkpointing = true
guidance_scale = 1
learning_rate = 0.0002
logit_std = 1
lr_scheduler = "constant"
lr_scheduler_num_cycles = 1
lr_scheduler_power = 1
max_data_loader_n_workers = 2
max_grad_norm = 1
max_timestep = 1000
max_train_epochs = 16
max_train_steps = 1600
mixed_precision = "bf16"
mode_scale = 1.29
network_alpha = 1
network_dim = 32
network_module = "networks.lora"
optimizer_type = "adamw8bit"
output_dir = "./test/output"
output_name = "name-of-lora"
persistent_data_loader_workers = true
save_every_n_epochs = 1
sdpa = true
seed = 42
sigmoid_scale = 1
timestep_sampling = "shift"
vae_dtype = "float16"
vae_spatial_tile_sample_min_size = 256
weighting_scheme = "none"

Not sure what I am doing wrong ;-(

[kohya-ss]

@bmaltais Sorry, there was a bug in argument definitions. I fixed it, so it should work now.

[bmaltais]

@kohya-ss This fixed the issue. Also, please review this pull request to consider merging the pyproject.toml and other related changes to enable the GUI to use your repo as a module and to enable the use of uv as an alternative method to install and run musubi-tuner.

[kohya-ss]

@bmaltais I got it. I will review this ASAP. Assuming that the issues with PyTorch and CUDA with uv will be resolved in the future, will there be any problems with the current pip installation even if this is merged?

[bmaltais]

The current pip based method still work as it used to. The uv method is "seperate". It actually should work fine with torch also. I added specific sources that make it work with literally no installation beside uv ;-)

It will take cake of installing the right release of python, install all the modules and run stuff. Literally no effort. And super quick. Give it a try.

[tool.uv.sources]
torch = [
  { index = "pytorch-cu124" },
]
torchvision = [
  { index = "pytorch-cu124" },
]

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"
explicit = true

[kohya-ss]

@bmaltais uv seems to work well. However, the command uv run cache_latents.py ... etc. seems to update uv.lock. Is this ok?

[bmaltais]

Uv can be told to support various releases of python. Specific module version for python versions can also be configured in the project.toml

[kohya-ss]

@bmaltais Maybe I need to do like this: uv run --frozen cache_text_encoder_outputs.py ... ?

[bmaltais]

I don’t know enough about uv.lock to know if it should be frozen or not… I notice it will get updated sometime. Especially on 1st run and possibly on module updates upstream.

[kohya-ss]

If the file is updated in the user's side, the next git pull will fail, so I think it is necessary to prevent the file from being changed. I'll try to find out how to do it, but if you find out anything, please let me know.

[bmaltais]

@kohya-ss Indeed, it probably need to be ignored and removed from the repo and dynamically calculated by uv when it run on each users machine. I don't think we need to provide it along with the pyproject.toml... I could remove it and add a gitignore entry for it...

Done.

I think I need to read a bit more about the uv.lock file and why it is being updated... Apparently the --frozen prevent update... but it also mean users could potentially (and will) to type it when executing... so perhaps it might be best to ignore it for now until a solution can be found...

[kohya-ss]

@bmaltais Thanks for the update.
I agree that it's probably best to ignore it. It looks like uv.lock will be created if I remove un.lock and run uv run ....

For now, it might be a good idea to merge this into main as an experimental feature, and to say that we're investigating the right way to configure uv and would welcome community feedback.

[bmaltais]

@kohya-ss Indeed. I agree.

[sdbds]

I was on a business trip over the weekend and just saw this.

As an early user of UV, I recommend using uv pip compile and uv sync to maintain backward compatibility of PIP.

https://docs.astral.sh/uv/reference/cli/#uv-pip-compile

uv-pip-compile can compile a complete synchronization dependency environment based on requirements.txt and project.toml.

https://docs.astral.sh/uv/reference/cli/#uv-sync

uv-sync syncing ensures that all project dependencies are installed and up-to-date with the lockfile.

We only need to compile additional GUI using requirements, and then quickly synchronize venv before running

[sdbds]

This is the script installation logic I wrote myself. First, I use uv pip compile locally to compile the requirements-uv.txt that is locked in the current environment.

Then use uv pip sync

~/.local/bin/uv pip install --upgrade setuptools wheel


if ($env:OS -ilike "*windows*") {
    ~/.local/bin/uv pip sync requirements-uv-windows.txt --index-strategy unsafe-best-match
    Check "Install main requirements failed"
}
else {
    ~/.local/bin/uv pip sync requirements-uv-linux.txt --index-strategy unsafe-best-match
    Check "Install main requirements failed"
}

https://github.com/sdbds/musubi-tuner-scripts/blob/470291edecbdfebdeff58f710978b729e7502547/1%E3%80%81install-uv-qinglong.ps1#L111-L120