Skip to content

Set up Windows dev environment with MSYS2

Jump to bottom
valtron edited this page Jul 31, 2025 · 30 revisions

MSYS2

Note: $VARS refer to strings you should substitute yourself. E.g. $DEV -> D:/dev

  1. Download from https://msys2.org
  2. Install into $DEV/msys2
  3. Run $DEV/msys2_shell.cmd
  4. Run pacman -Syuu
  5. Close the shell; reopen it, and run pacman -Syuu again, just in case :p

Pacman

pacman is the package manager bundled with msys. Use it to install useful things like gcc, flex, bison, git. The commands are pretty cryptic, so use the Pacman/Rosetta.

Set up $PATH

  • Open "Environment Variables > System Variables > Path"
  • At the end, add $DEV/msys2/usr/bin

Set up $HOME

By default, msys will use $DEV/msys2/home as your home folder. If you want to use your existing home folder, set a $HOME env variable:

  • Under "Environment Variables > User variables", add HOME -> %USERPROFILE%

Then edit $DEV/msys2/etc/nsswitch.conf to set db_home: /%H.

Also, SSH insists on using MSYS' /home, but you can get around that by adding this line to /etc/fstab:

C:/Users /home ntfs binary,noacl,auto 1 1

SSH

To protect yourself from things like this, you should use a different SSH key for every service, and stop SSH from trying every possible authentication method when connecting to a host.

~/.ssh/config should look like this:

# For every service, create a new keypair:
# $ ssh-keygen -f ~/.ssh/id/service-name -t ed25519
# And add one of these blocks:
Host service-name # alias; to connect, do `ssh service-name`
	User your_username
	# If you make service-name the URL, you can omit this
	HostName service.url.com
	PubkeyAuthentication yes
	IdentityFile ~/.ssh/id/service-name

# This stops SSH trying to authenticate to unknown hosts using every key it knows about
Host *
	PubkeyAuthentication no
	IdentitiesOnly yes

Git

  1. Open an msys shell
  2. Run pacman -S git
  3. If you want to use git gui/gitk,
    1. Run pacman -S mingw-w64-x86_64-tk
    2. Add $DEV/msys2/mingw64/bin to $PATH

Better Git defaults

Pull should rebase by default:

git config --global --add pull.rebase true

push --force should fail if remote is different than expected:

git config --global --add push.forceWithLease true

Probably redundant because of pull.rebase, but make extra sure you it doesn't automatically create merges:

git config --global --add pull.ff only

Problems with git gui

You might get this problem with git gui; to fix, add env var GIT_GUI_LIB_DIR -> $DEV/msys2/usr/share/git-gui/lib.

Git Autocomplete

Add this to the bottom of ~/.bashrc:

source /usr/share/git/completion/git-completion.bash

MSYS shell

$DEV/msys2/*_shell.cmd opens $DEV/msys2/usr/bin/mintty.exe, which has problems with the Python installed by the official Python installers. If you prefer, you can use $DEV/msys2/usr/bin/bash.exe by making a shortcut to it (on your desktop, for example).

To customize:

  1. (right-click shortcut) > Properties
  2. Change "Shortcut > Start in:" to be the directory you want it to open to, e.g. %HOME%/Desktop
  3. Fiddle with settings in Options, Font, Layout, and Colors.
    • The default Windows console colours are ugly in some combinations (dark blue on black, for example). You can change the default colours easily through the registry. Note that you have to change the values in the registry before creating the shortcut.

Custom shell prompt

Put this in ~/.bashrc for a custom prompt:

function parse_git_branch() {
	git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
}
PROMPT_USER="\[\033[32m\]\u@\h\[\033[00m\]"
PROMPT_DIR="\[\033[33m\]\w\[\033[00m\]"
PROMPT_BRANCH="\[\033[35m\]\$(parse_git_branch)\[\033[00m\]"
export PS1="$PROMPT_USER $PROMPT_DIR$PROMPT_BRANCH"$'\n$ '

Environment Variables

Environment variables in windows are under:

  • (right-click start) > System > Advanced System Settings > Advanced > Environment Variables...

You can also set env vars in your .bash_profile/.bashrc.

Python

Dealing with PEP8-ers

Create a filter named tabspace4:

git config --global filter.tabspace4.smudge '/usr/bin/unexpand --tabs=4 --first-only'
git config --global filter.tabspace4.clean '/usr/bin/expand --tabs=4 --initial'

Then in the repo's .git/info/attributes, add:

*.py  filter=tabspace4

Then, in your (clean; if not, stash) repo do:

rm .git/index
git checkout HEAD -- "$(git rev-parse --show-toplevel)"

Virtualenv

To use virtualenvs without the activate/deactivate nonsense, in your .bashrc add:

PYROOT="path to your python install"
VENV=.venv
case "$OSTYPE" in
	# `virtualenv` uses different directories on different OSes to keep you on your toes.
	msys | cygwin) VENV_BIN=$VENV/Scripts ;;
	*)             VENV_BIN=$VENV/bin     ;;
esac

function py {
	if [ -d "$VENV" ]; then
		local PRE=$VENV_BIN
	else
		local PRE=$PYROOT
	fi
	PYTHONPATH="." $PRE/python "$@"
}

and use py instead of python (and py -m pip instead of pip) from now on. To help enforce this, you should also add:

function pip {
	echo "Don't use \`pip\`. Use \`py -m pip\`."
}

function python {
	echo "Don't use \`python\`. Use \`py\`."
}

Now, when you run py, it first tries to use python inside the .venv of the current directory, otherwise the system-wide one.

For executables installed by python packages (e.g. django-admin ...), figure out the equivalent py -m <module name> ... for doing the same thing.

If you want to keep using the python executable directly, you should also add . to PYTHONPATH globally:

export PYTHONPATH="."

Building extension modules.

Setuptools assumes you have MSVC if you use Windows. To change the compiler it uses, create $HOME/pydistutils.cfg:

[build]
compiler=mingw32

More details here.

Right-click Context Menu Entries

git-bash has a special --cd option to set the directory on startup, which regular bash doesn't. To get around that, create $DEV/bash_cd.sh:

if [ "z$1" != "z" ]; then
	cd $1
fi
bash

Next, create a regedit file (*.reg):

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Classes\Directory\Background\shell\bash]
@="Bash"
"Icon"="C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
"Position"="Bottom"

[HKEY_CURRENT_USER\SOFTWARE\Classes\Directory\Background\shell\bash\command]
@="$DEV\\msys2\\usr\\bin\\bash.exe"

[HKEY_CURRENT_USER\SOFTWARE\Classes\Directory\shell\bash]
@="Bash"
"Icon"="C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
"Position"="Bottom"

[HKEY_CURRENT_USER\SOFTWARE\Classes\Directory\shell\bash\command]
@="$DEV\\msys2\\usr\\bin\\bash.exe $DEV\\bash_cd.sh \"%1\""

Note the paths have to be Windows-style, with escaped (double) backslashes, and that the "Background" entry's command should not contain %1. Feel free to change the "Icon" and "Position" properties. Execute the regedit file and you're done.

Console Colours

Save and run this as a *.reg file if you want nicer console colours.

Note, this doesn't affect Bash/cmd shortcuts that already exist, so you'll need to do this first.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Console]
"ColorTable00"=dword:000c0c0c
"ColorTable01"=dword:00da3700
"ColorTable02"=dword:000ea113
"ColorTable03"=dword:00dd963a
"ColorTable04"=dword:001f0fc5
"ColorTable05"=dword:00981788
"ColorTable06"=dword:00009cc1
"ColorTable07"=dword:00cccccc
"ColorTable08"=dword:00767676
"ColorTable09"=dword:00ff783b
"ColorTable10"=dword:000cc616
"ColorTable11"=dword:00d6d661
"ColorTable12"=dword:005648e7
"ColorTable13"=dword:009e00b4
"ColorTable14"=dword:00a5f1f9
"ColorTable15"=dword:00f2f2f2
Clone this wiki locally