package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (33)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

6.0.0-alpha00.tar.gz
md5=8a88c5d5fcb01d179bbb12e6b6888dca
sha512=bfecd3fa0a3461a3368bd7724e2fce7a751ba3899d590d5b08bc4257b058ca34ec25de1a3ead6585528afe77c6ca6db1c3e2d2421d6a773c845ef091472d2ed9

Description

A promise is a value that may become determined in the future.

Lwt provides typed, composable promises. Promises that are resolved by I/O are resolved by Lwt in parallel.

Meanwhile, OCaml code, including code creating and waiting on promises, runs in a single thread by default. This reduces the need for locks or other synchronization primitives. Code can be run in parallel on an opt-in basis.

Published: 24 Jul 2025

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become determined in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.

Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:

open Lwt.Syntax

let () =
  let request =
    let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = Lwt_unix.sleep 5. in
    Lwt.return None
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." Lwt.pick races promises against each other, and behaves as the first one to complete. Lwt_main.run forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

  • The core library Lwt provides promises...
  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.
  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.
  • Lwt_process is for subprocess handling.
  • Lwt_preemptive spawns system threads.
  • The PPX syntax allows using all of the above without going crazy!
  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!

Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.
  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.
  • Mirage has a nicely-written Lwt tutorial.
  • An example of a simple server written in Lwt.
  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads" or just "threads." This will be fixed in the new manual. 'a Lwt.t is a promise, and has nothing to do with system or preemptive threads.


Contact

Open an issue, visit Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.
  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)
  • The documentation always needs proofreading and fixes.
  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.
  • Any feedback is welcome, including how to make contributing easier!

Libraries to use with Lwt

Dependencies (5)

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1.0"
  4. ocaml >= "4.08" & < "5.5"
  5. dune >= "2.7"

Dev Dependencies (3)

  1. bisect_ppx with-test
  2. odoc with-doc & >= "2.3.0"
  3. ocamlfind with-dev-setup & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. awa-mirage
  16. aws-lwt
  17. aws-s3-lwt >= "4.8.1"
  18. awsm-lwt
  19. awso-lwt
  20. azure-cosmos-db < "0.4.0"
  21. azure-cosmos-db-lwt
  22. balancer
  23. bastet_lwt
  24. bimage-lwt
  25. bistro
  26. bizowie-api
  27. brisk-reconciler
  28. builder
  29. builder-web
  30. bun >= "0.3.3"
  31. cachet-lwt
  32. calculon
  33. caldav
  34. camltc
  35. canary
  36. capnp-rpc-lwt < "2.0"
  37. capnp-rpc-unix < "2.1"
  38. caqti-lwt
  39. caqti-mirage
  40. carton < "1.0.0"
  41. carton-git
  42. carton-lwt
  43. catala-format >= "0.2.0"
  44. cf-lwt
  45. chamelon
  46. chamelon-unix
  47. chamo
  48. charrua-client
  49. charrua-unix
  50. chess_com_api
  51. ciao_lwt
  52. clz
  53. cmdtui-lambda-term
  54. coap
  55. coap-server-lwt
  56. cohttp-curl-lwt
  57. cohttp-lwt
  58. cohttp-lwt-jsoo
  59. cohttp-lwt-unix
  60. cohttp-mirage
  61. cohttp-server-lwt-unix
  62. comby
  63. comby-semantic
  64. conan-lwt
  65. conduit-lwt
  66. conduit-lwt-unix
  67. cowabloga
  68. crunch
  69. cstruct-lwt
  70. csv-lwt
  71. ctypes >= "0.15.0" & < "0.21.1"
  72. ctypes-foreign >= "0.21.1"
  73. curl_lwt
  74. current
  75. current-albatross-deployer
  76. current_docker
  77. current_examples
  78. current_git
  79. current_github
  80. current_gitlab
  81. current_ocluster
  82. current_rpc
  83. current_slack
  84. current_web
  85. dap
  86. data-encoding < "0.1.1"
  87. devkit >= "1.2"
  88. distributed-lwt
  89. dkim-bin < "0.8.0"
  90. dkim-lwt-unix
  91. dkim-mirage
  92. dlm
  93. dmarc
  94. dns-certify
  95. dns-cli
  96. dns-client < "7.0.3"
  97. dns-client-lwt
  98. dns-client-mirage
  99. dns-forward
  100. dns-forward-lwt-unix
  101. dns-lwt
  102. dns-mirage
  103. dns-resolver
  104. dns-server
  105. dns-stub
  106. dnsrobot
  107. dnssd
  108. docker_hub
  109. docteur >= "0.0.2"
  110. docteur-solo5
  111. docteur-unix >= "0.0.5"
  112. doi2bib
  113. dream
  114. dream-httpaf
  115. dream-pure
  116. dream-serve < "1.0.1"
  117. dropbox
  118. dune >= "3.17.2"
  119. dune-rpc-lwt
  120. earlybird
  121. elasticsearch-cli
  122. emoji = "2.0.0"
  123. equinoxe
  124. ethernet
  125. ez_api >= "1.2.0" & < "3.0.0"
  126. ezcurl-lwt
  127. ezjs_min < "0.2"
  128. ezjsonm-lwt
  129. ezresto
  130. ezresto-directory >= "0.5"
  131. faraday-lwt
  132. faraday-lwt-unix
  133. fat-filesystem
  134. fiber-lwt
  135. fsevents-lwt
  136. fswatch_lwt
  137. fuseau-lwt
  138. gdbprofiler
  139. git
  140. git-cohttp
  141. git-cohttp-unix
  142. git-kv >= "0.2.0"
  143. git-mirage
  144. git-paf
  145. git-unix >= "3.2.0"
  146. github
  147. github-hooks
  148. github-unix >= "4.4.0"
  149. gitlab-unix
  150. gitlab_pipeline_notifier
  151. gluten-lwt
  152. gluten-lwt-unix < "0.4.0"
  153. gluten-mirage < "0.4.0"
  154. graphql-lwt
  155. gremlin
  156. grpc-lwt
  157. guardian
  158. gufo
  159. h1
  160. h1-lwt-unix
  161. h2-lwt
  162. h2-lwt-unix < "0.10.0"
  163. h2-mirage
  164. happy-eyeballs-lwt
  165. happy-eyeballs-mirage
  166. hidapi-lwt
  167. hiredis >= "0.6"
  168. hl_yaml
  169. hockmd
  170. http-lwt-client
  171. http-mirage-client
  172. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  173. httpaf-lwt-unix
  174. httpun-lwt
  175. httpun-mirage
  176. httpun-ws-lwt
  177. hvsock
  178. i3ipc
  179. influxdb-lwt
  180. inotify >= "2.4"
  181. inquire < "0.3.0"
  182. interface-prime-lwt
  183. ip2location
  184. ip2locationio
  185. ip2whois
  186. ipv6-multicast-lwt
  187. irc-client-lwt
  188. irc-client-lwt-ssl
  189. irc-client-tls
  190. irmin
  191. irmin-bench
  192. irmin-chunk
  193. irmin-cli
  194. irmin-client
  195. irmin-containers
  196. irmin-fs
  197. irmin-git
  198. irmin-graphql
  199. irmin-http
  200. irmin-indexeddb
  201. irmin-layers
  202. irmin-mirage-git
  203. irmin-mirage-graphql
  204. irmin-pack
  205. irmin-server
  206. irmin-test
  207. irmin-unix
  208. irmin-watcher
  209. joolog
  210. jose < "0.9.0"
  211. js_of_ocaml-lwt
  212. jsoo_broadcastchannel
  213. jsoo_storage
  214. jupyter
  215. jupyter-kernel
  216. kafka < "0.5"
  217. kafka_lwt
  218. kappa-library
  219. ke >= "0.5"
  220. kinetic-client
  221. kubecaml
  222. lambda-runtime
  223. lambda-term
  224. lambda_streams_lwt
  225. launchd
  226. ldp
  227. learn-ocaml
  228. learn-ocaml-client
  229. ledgerwallet >= "0.4.0"
  230. letsencrypt < "2.0.0"
  231. letsencrypt-app
  232. letsencrypt-dns < "2.0.0"
  233. letters
  234. lichess_api
  235. links
  236. llama
  237. lru_cache
  238. lwt-canceler
  239. lwt-dllist
  240. lwt-exit
  241. lwt-parallel
  242. lwt-pipe
  243. lwt-pipeline
  244. lwt-watcher
  245. lwt_camlp4
  246. lwt_direct != "6.0.0~beta01"
  247. lwt_domain
  248. lwt_eio < "0.6"
  249. lwt_glib
  250. lwt_log
  251. lwt_ppx != "6.0.0~beta01"
  252. lwt_react
  253. lwt_retry
  254. lwt_ssl
  255. mariadb >= "1.2.0"
  256. markdown_monolith
  257. markup = "0.7.6"
  258. markup-lwt
  259. mdx
  260. mechaml
  261. mehari-lwt-unix
  262. mehari-mirage
  263. memtrace-mirage
  264. metrics-influx
  265. metrics-lwt
  266. metrics-unix
  267. migra
  268. mimic
  269. mindstorm-lwt
  270. mirage < "4.0.0"
  271. mirage-block >= "2.0.1"
  272. mirage-block-ccm
  273. mirage-block-combinators
  274. mirage-block-lwt
  275. mirage-block-partition
  276. mirage-block-ramdisk
  277. mirage-block-solo5
  278. mirage-block-unikraft
  279. mirage-block-unix >= "2.14.2"
  280. mirage-block-xen
  281. mirage-channel >= "4.0.1"
  282. mirage-channel-lwt
  283. mirage-clock-lwt
  284. mirage-clock-unix < "4.2.0"
  285. mirage-console-lwt
  286. mirage-crypto-rng < "0.11.3"
  287. mirage-crypto-rng-lwt
  288. mirage-crypto-rng-mirage
  289. mirage-device >= "2.0.0"
  290. mirage-flow >= "3.0.0"
  291. mirage-flow-combinators
  292. mirage-flow-lwt
  293. mirage-flow-unix
  294. mirage-fs >= "4.0.0"
  295. mirage-fs-lwt
  296. mirage-kv >= "3.0.1"
  297. mirage-kv-lwt
  298. mirage-kv-unix
  299. mirage-net >= "4.0.0"
  300. mirage-net-lwt
  301. mirage-net-macosx
  302. mirage-net-solo5
  303. mirage-net-unikraft
  304. mirage-net-unix
  305. mirage-net-xen
  306. mirage-profile
  307. mirage-protocols >= "7.0.0"
  308. mirage-protocols-lwt
  309. mirage-qubes
  310. mirage-qubes-ipv4
  311. mirage-runtime
  312. mirage-sleep
  313. mirage-solo5
  314. mirage-stack = "3.0.0"
  315. mirage-stack-lwt
  316. mirage-time >= "3.0.0"
  317. mirage-time-lwt
  318. mirage-time-unix
  319. mirage-types-lwt
  320. mirage-unikraft
  321. mirage-unix
  322. mirage-vnetif
  323. mirage-xen
  324. monorobot
  325. moonpool-lwt < "0.11"
  326. mqtt
  327. mrmime >= "0.5.0"
  328. multipart-form-data
  329. multipart_form >= "0.2.0" & < "0.4.0"
  330. multipart_form-cohttp-lwt < "0.6.0"
  331. multipart_form-lwt
  332. mwt
  333. naboris
  334. nbd >= "4.0.3"
  335. nbd-tool
  336. nbd-unix
  337. neo4j_bolt
  338. nocrypto
  339. nottui-lwt
  340. notty-community
  341. nproc
  342. nsq
  343. obuilder
  344. obus >= "1.2.1"
  345. ocaml-ai-sdk
  346. ocluster
  347. ocluster-api
  348. ocluster-worker
  349. ocplib-resto
  350. ocsigenserver
  351. ocsipersist
  352. ocsipersist-dbm
  353. ocsipersist-lib
  354. ocsipersist-pgsql
  355. ocsipersist-sqlite
  356. oframl
  357. ojs_base
  358. omigrate
  359. oneffs
  360. opam-check-npm-deps >= "4.1.0"
  361. opam-publish >= "3.0.0"
  362. opencage
  363. opentelemetry-client-cohttp-lwt
  364. opentelemetry-client-ocurl-lwt
  365. opentelemetry-cohttp-lwt >= "0.4"
  366. opentelemetry-lwt
  367. opium
  368. opium-graphql
  369. opium_kernel
  370. opomodoro
  371. order-i3-xfce
  372. ordma
  373. oskel >= "0.3.0"
  374. ounit-lwt < "2.2.0"
  375. ounit2-lwt
  376. owork
  377. ozulip
  378. paf
  379. paf-cohttp
  380. passage < "0.1.8"
  381. pcap-format < "0.5.2"
  382. petrol
  383. pgn_parser
  384. pgx_lwt
  385. pgx_lwt_mirage
  386. pgx_lwt_unix < "2.0"
  387. piaf < "0.2.0"
  388. picos >= "0.3.0" & < "0.5.0"
  389. picos_lwt
  390. picos_meta
  391. plebeia >= "2.0.0"
  392. plotkicadsch
  393. posix-getopt >= "4.0.2"
  394. ppx_defer >= "0.4.0"
  395. ppx_deriving_rpc
  396. ppx_rapper_lwt
  397. proc-smaps
  398. prof_spacetime
  399. prometheus
  400. prometheus-app
  401. promise_jsoo_lwt
  402. protocol-9p
  403. protocol-9p-unix
  404. proton
  405. pxshot
  406. qcow
  407. qcow-stream
  408. qcow-tool
  409. qcow-types
  410. qdrant < "0.2.0"
  411. qfs
  412. quests
  413. quickterface
  414. rawlink < "2.1"
  415. rawlink-lwt
  416. rdf_json_ld
  417. rdf_lwt
  418. redis-lwt
  419. reparse-lwt
  420. reparse-lwt-unix
  421. resource-pooling
  422. resp
  423. resp-mirage >= "0.10.0"
  424. resp-unix >= "0.10.0"
  425. resto
  426. resto-cohttp-client >= "0.4"
  427. resto-cohttp-self-serving-client
  428. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  429. resto-directory >= "0.4"
  430. ringo-lwt
  431. river
  432. rock
  433. rpclib-js
  434. rpclib-lwt
  435. SZXX < "4.0.0"
  436. sanddb
  437. scgi
  438. sendmail-lwt
  439. sendmail-mirage
  440. serial
  441. server-reason-react
  442. session-cohttp-lwt
  443. session-cookie-lwt
  444. session-postgresql-lwt
  445. sessions
  446. shared-block-ring
  447. shared-memory-ring-lwt
  448. sherlodoc
  449. sihl < "0.2.0"
  450. slack
  451. slacko
  452. slipshow
  453. smtml >= "0.7.0"
  454. speed
  455. spin < "0.8.0"
  456. spoke
  457. statocaml
  458. stk
  459. stog
  460. swapfs
  461. syguslib-utils
  462. syndic >= "1.4" & < "1.6.0"
  463. tar-mirage
  464. tar-unix
  465. tcpip
  466. telegraml
  467. terminus
  468. testcontainers
  469. testo-lwt
  470. tezt
  471. tidy_email
  472. timmy-lwt
  473. tls >= "0.10.6" & < "0.16.0"
  474. tls-lwt
  475. tls-mirage
  476. tube
  477. tuntap
  478. twirp_cohttp_lwt_unix
  479. uring
  480. uspf
  481. uspf-lwt
  482. uspf-mirage
  483. utcp
  484. utop
  485. uwt
  486. vchan
  487. vchan-unix
  488. vchan-xen
  489. vercel
  490. vhd-format-lwt
  491. vmnet
  492. vue-jsoo < "0.3"
  493. wayland < "2.0"
  494. webauthn
  495. xen-evtchn
  496. xen-evtchn-unix
  497. xen-gnt
  498. xen-gnt-unix
  499. xenstore
  500. xenstore-tool
  501. xenstore_transport
  502. xlsx2csv
  503. yocaml_git
  504. yocaml_unix < "2.0.0"
  505. zarr-lwt
  506. zmq-lwt >= "5.2.1"

Conflicts

None