Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

As of 2008, Gentoo on Cygwin is unmaintained.[1] See for a better alternative.




In order for Portage to operate properly, you will need, at a minimum, the following Cygwin binary packages (and their dependencies) installed:

In order for Portage to properly build system, you will also need:

You should be warned that my rudimentary system package set includes app-editors/nano. That said, I advise against installing nano.

See to obtain the setup program for installing these packages.


Though dominated by Python scripts, Portage actually makes use of two compiled files. As such, I have prepared a "binary" that you can download from Unroll it by hand as you would a raw Cygwin installation binary tarball:

cd /
tar -xjvf ~/portage-2.0.54-2.tar.bz2

The more GPL-conscious among you should notice that the original source tarball and ebuild are posted there along with my patches and modified ebuild.

Portage tree

"Managed" mounts

Before you get too far along in rsync'ing or otherwise downloading your portage tree, you should know that it contains some characters that are not permitted in Windows file systems. This turns out to be a more common problem than case insensitivity. Fortunately, Cygwin, in its great and mighty wisdom, has a way to circumvent both of these issues by rewriting file names in a manner similar to URL escaping, but it incurs a dreadful (but acceptable in this case) performance hit. The process is to use something called "managed" mounts.

cd /usr
mkdir -p .managed/portage
mkdir portage
mount -o managed `cygpath -m /usr/.managed/portage` /usr/portage

Once the configuration process is complete, emerge --sync will Do The Right Thing. In fact, you can run the command to retrieve your initial tree.

FIXME: Group configuration should be discussed before suggesting emerge can be run

WARNING: You should know that mv and other utilities that may find a way to move an entire folder into a managed mount at once may not trigger Cygwin to rewrite filenames. Utilities like rsync are far more reliable. Failure to mind this may result in weird problems where ls might reveal a file called ChangeLog, but if the file hasn't been renamed to %43hange%4Cog, any attempt to open it will fail, as the file %43hange%4Cog is not really there.

Cygwin-specific and other overlays

At the time of this writing, the mainstream portage tree does not support Cygwin or the cygwin keyword. You will require, therefore, an overlay that starts with something like You should extract it into /usr/local/portage.cygwin:

mkdir /usr/local/portage.cygwin
cd /usr/local/portage.cygwin
tar -xzvf ~/cygwin-overlay.tar.gz
FIXME: Documentation on auto-generating cygwin-binary ebuilds from the Cygwin setup.ini tree (and/or possible hosting of the same) should be put here.


What follows are the steps I followed to bootstrap a new machine, along with gently sanitized copies of the configuration files that I use.

User accounts and groups

Warning: The following error:
 [Errno 22] Invalid argument:
Is caused by cygwin when not found a group or user into Windows(R) users or groups. If appear it, check the /etc/passwd or /etc/group files.
# If Administrators group looks like Administrators:S-1-5-32-544:0: 
echo 'portage:S-1-5-32-544:250:root' >> /etc/group
# If root looks like 'root:S-1-5-32-544:0:'
echo 'wheel:S-1-5-32-544:10:' >> /etc/group
# If SYSTEM looks like 'SYSTEM:*:18:544:,S-1-5-18::'
echo 'portage:*:250:250:,S-1-5-18::' >> /etc/passwd

You will need to log out and log in for the group assignments to pan out.

DLL rebasing

It will be necessary to rebase python's dynamic dlls.

Warning: the rebase process is dangerous at best, though I haven't experienced any problems to date. Be prepared to reinstall python if it doesn't work for you.
cd /usr/lib/python2.4/lib-dynload
ls *.dll >dll.lst
rebase -b 0x70000000 -o 0x10000 -T dll.lst


The most notable feature of this file is the invocation of the portage overlay. It also includes a userpriv entry in FEATURES, which enables some things to work out of a user's home directory instead of the mythical /root folder. This includes subversion sources.

File: /etc/make.conf
CFLAGS="-march=pentium3 -O3 -pipe"
FEATURES="userpriv test"

Note: FEATURES="test" is recommended as Gentoo on Cygwin is still experimental.


This file provides the critical service of remapping certain common dependencies (which will be inevitably masked) to their cygwin binary equivalents. With an appropriately configurated overlay, portage can actually install these binaries.

FIXME: tell the world how to do this...

It should be noted, however, that portage cannot merge all packages into a live system. In particular, it cannot replace running executables, most notably python, bash, and cygwin1.dll.

File: /etc/portage/profile/virtuals
sys-libs/ncurses cygwin-binaries/ncurses
sys-apps/sysvinit cygwin-binaries/sysvinit
dev-util/subversion cygwin-binaries/subversion
sys-devel/automake cygwin-binaries/automake
sys-devel/libtool cygwin-binaries/libtool
sys-devel/autoconf cygwin-binaries/autoconf
sys-devel/gettext cygwin-binaries/gettext cygwin-binaries/gettext-devel cygwin-binaries/libgettextpo0
virtual/libintl cygwin-binaries/gettext cygwin-binaries/gettext-devel cygwin-binaries/libgettextpo0

Note: The lines starting with sys-devel/gettext and virtual/libintl are needed if you have the USE-flag nls


This file is a source of great sanity in using portage sensibly on Cygwin. In conjunction with /etc/portage/profile/virtuals as described above, this file specifies explicitly which packages (with their versions) that portage should not worry about. This should be populated with data reflective of packages installed using Cygwin setup.

File: /etc/portage/profile/package.provided

It should be noted that cygcheck -c -d can give you a dump of all the packages installed in that manner. The script below can generate the /etc/portage/profile/package.provided for you.

Code: Generate package.provided
cygcheck -c -d  | \
  awk '{print "cygwin-binaries/"$1"-"$2}' | \
  dos2unix | \
  sed -e 's/-\([0-9]\+\)$/-r\1/' > /etc/portage/profile/package.provided

Warning: This script will likely generate a handful of invalid package atoms. Portage will whine at you every time it runs, but it will do its job for the most part. You can manually remove/fix the invalid atoms.


You shall also require a symlink at /etc/make.profile to the default-cygwin profile:

ln -s /usr/local/portage.cygwin/profiles/default-cygwin /etc/make.profile


At this point, you may now issue your first portage commands to get yourself going.

emerge --sync
emerge patch # if you did not install cygwin's patch
emerge system

The emerge system command should run without error. You'll quickly notice, however, that my definition of system is quite dull.

Further Discussion

Scattered bits of additional notes are available at

Enjoy. --Jalonso 08:52, 1 March 2006 (GMT)

  • Why is this a HowTo instead of a single python or bash script (with shUnit2 or pyUnit sanity checks)? --BrianFennell

Last modified: Wed, 30 Jul 2008 11:12:00 +0000 Hits: 17,754