Update setup instructions

[tobyhodges]

This updates the setup instructions for Python workshops. A recent blog post provides more context for this change. Specifically, this PR updates the instructions to reflect that we recommend Miniforge instead of Anaconda Python.

One of the most important changes here is to include an environment.yml for learners to use to create an environment that they can work in during the workshop/while following the lesson. When this PR is ready to merge, I will release a new version of the example data on FigShare that contains the environment file. Since I guess it will be helpful for testing purposes -- and because it is probably a good idea to keep a copy in the lesson repo too -- you can find my proposed version of that file in this PR.

[github-actions]

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• 🎯 correct output
• 🖼️ correct figures
• ❓ new warnings
• ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/datacarpentry/image-processing/compare/md-outputs..md-outputs-PR-342

The following changes were observed in the rendered markdown documents:

 files/environment.yml (new) | 11 +++++++++++
 md5sum.txt                  |  2 +-
 setup.md                    | 40 ++++++++++++++++------------------------
 3 files changed, 28 insertions(+), 25 deletions(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2025-05-07 13:27:50 +0000

[K-Meech]

Thanks @tobyhodges - looks good! I tried this out on my Windows laptop, and all worked well 😄 I left a few comments below.

@datacarpentry/image-processing-curriculum-maintainers - it would be great if you could try this out too, especially if you're on mac/linux

[K-Meech]

Looks good to me - thanks @tobyhodges ! I'll leave this open for a while longer, in case the other maintainers have any input

[K-Meech]

@datacarpentry/image-processing-curriculum-maintainers - do feel free to add any further comments / suggestions, otherwise I'll merge this PR at the end of this week

[mkcor]

I'm not sure it's obvious that, on Unix-like platforms, you need to run

bash Miniforge3-$(uname)-$(uname -m).sh

from the terminal to install Miniforge... I would add a line about this. Is it obvious on Windows? I guess so, if you need to double-click what you just downloaded.

[K-Meech]

Yes - on Windows it's an .exe file, so you just double-click the downloaded file.

[tobyhodges]

I added a link to the central instructions, which are more detailed, in 9c8345e.

[mkcor]

I just tried on Linux x86_64, I downloaded the environment.yml from this PR, but somehow...

$ mv ~/Downloads/environment.yml .
$ conda env create -f environment.yml
Solving environment: failed

CondaValueError: Malformed version string '~': invalid character(s).

$ cat environment.yml 
name: dc-image
channels:
  - conda-forge
dependencies:
  - python>=3.11
  - jupyterlab
  - numpy
  - matplotlib
  - scikit-image
  - ipympl
  - imageio

I tried editing the file by removing the Python version, but got the same error. 🤔

[tobyhodges]

CondaValueError: Malformed version string '~': invalid character(s).

@mkcor is it possible that your conda version needs to be updated?

[mkcor]

@mkcor is it possible that your conda version needs to be updated?

Oh, yes, most likely:

$ conda --version
conda 4.5.11

Thanks, @tobyhodges!

CondaValueError: Malformed version string '~': invalid character(s).

And I'm getting the same error when I try $ conda update conda... I haven't been able to upgrade/uninstall/reinstall in a recommended fashion; currently $ sudo rm -rf ~/miniconda3/ is hanging, so I don't want to hold this PR. Feel free to go ahead and merge.

[mkcor]

I could follow the setup instructions successfully! 🎉

I have installed a fresh version (25.3.0) of conda via Miniforge and I'm running Debian GNU/Linux 12 (bookworm).

[K-Meech]

Thanks all for the input! @tobyhodges feel free to merge when you're ready - if you could update the FigShare with the new environment file at the same time - that would be great 😄

[tobyhodges]

I have published a new version of the data on FigShare and will merge this now.

[tobyhodges]

Thank you @K-Meech & @mkcor for your help 🙌