I've never been to Portugal, but we're considering checking it out because of a relatively large English speaking population and a Mediterranean climate, which we've gotten used to and are not eager to give up.
We've been a number of years ago and we enjoyed it. My wife and I are planning to take another trip next year as a more focused exploratory trip. Following that we need to spend some time elsewhere for a while.
For us, this is being considered not just staying in Portugal but as a base from which to explore the rest of Europe. I currently have EU citizenship, British, but won't be able to make the move to Portugal before the Brexit divorce is over. I may regain EU citizenship since my sub-citizenship is Scottish. However, at this point I'm not assuming that will work out. For non-EU citizens you need to get a visa for long stay before you go to Portugal. I've found the forms online and some but not much discussion of how hard the process is. This is an area that I would like to know more about.
When you arrive you need to file a bunch of paperwork for registration of your residency and get a financial number (similar to a SSN) etc. etc. You will need to provide your own health insurance. I would be interested in hearing reports of how this process all worked out.
You don't actually file for the non-habitual residency until the following year when you file your taxes. To be a non-habitual resident you need to meet one of two qualifications: 1) remain in Portugal for 183 days in a year; or 2) have a dwelling in Portugal on 31 December with the intention to hold it as your habitual residence. You get 10 years under this scheme.
The tax free status gives you a break on income earned in Portugal in a high value add occupation (doctor, engineer, lawyer, etc.) and you don't get taxed in Portugal on earnings in another country which were subject to tax in the source country. That last one is a bit confusing and I've seen interpretations that say that dividends, interest, and capital gains (amongst other things) are not taxed. However, interpretations from probably more reliable sources say that capital gains are taxed since they are not "subject to taxation in the source country" under most tax treaties. This may not matter much for Americans since they will have to pay tax to the US no matter what though this might mean that there is no extra tax on the top if the Portuguese rate is higher since they avoid that under this special status (except for capital gains).
So, since I want to use Portugal for a base to explore Europe and won't be there for the required 183 days I plan to buy a place to occupy over the 4-6 months of the winter/late fall/early spring. If a rental during that time would count as a habitual residence then that might work but I would like to be able to leave stuff in the place while I'm traveling the rest of the year. I might consider renting the place out during that time.
If the interpretation is correct that capital gains
is taxable in Portugal then I will probably need to structure my non-tax deferred accounts to need no rebalancing (e.g. total world index or something like it) and to live off the dividends and supplement that with cash from CDs or similar while I am a non-habitual resident of Portugal.