Let me ask right at the start: what is Riemann integration really used for?
As far as I'm aware, we use Lebesgue integration in:
theory of PDE's
and really, anywhere I can think of where integration is used (perhaps in the form of Haar measure, as a generalization, although I'm sure this is vastly incomplete picture).
Let me state a well known theorem:
Let $f:[a,b]\to\mathbb R$ be bounded function. Then:
(i) $f$ is Riemann-integrable if and only if $f$ is continuous almost everywhere on $[a,b]$ (with respect to Lebesgue measure).
(ii) If $f$ is Riemann-integrable on $[a,b]$, then $f$ is Lebesgue-integrable and Riemann and Lebesgue integrals coincide.
(I will try to be fair, we use this result and Riemann integration to calculate many Lebesgue integrals)
From this we can conclude that Riemann-integrability is a stronger condition and we might naively conclude that it might behave better. However it does not; Riemann integral does not well behave under limits, while Lebesgue integral does: we have Lebesgue monotone and dominated convergence theorems.
Furthermore, I'm not aware of any universal property of Riemann integration, while in contrast we have this result presented by Tom Leinster; it establishes Lebesgue integration as initial in appropriate category (category of Banach spaces with mean).
Also, I'm familiar with Lebesgue-Stiltjes integral, greatly used for example in probability theory to define appropriate measures. I'm not so familiar with the concept or usage of Riemann-Stiltjes integral, and I'd greatly appreciate if someone could provide any comparison.
As far as I can tell, the only accomplishment of Riemann integration is the Fundamental theorem of calculus (not to neglect it's importance). I'm very interested to know if there are more important results.
To summarize the question:
Where is Riemann integral used compared to Lebesgue integral (which seems much better behaved) and why do we care?
It seems that it is agreed upon that Riemann integration primarily serves didactical purpose in teaching introductionary courses in analysis as a stepping stone for Lebesgue integration in later courses when measure theory is introduced. Also, improper integrals were brought as an example of something Lebesgue integration doesn't handle well. However, in several answers and comments we have another notion - that of a gauge integral (Henstock–Kurzweil integral, (narrow) Denjoy integral, Luzin integral or Perron integral). This integral not only generalizes both Riemann and Lebesgue integration, but also has much more satisfactory Fundamental theorem of calculus: if a function is a.e. differentiable than it's differential is gauge-integrable and conversely function defined by gauge integral is a.e. differentiable (here almost everywhere means everywhere up to a countable set).
Thank you for all the answers. This question should probably be altered to the following form (in more open-ended manner):
What are pros and cons of different kinds of integrals, and when should we use one over the other?