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 (27)

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

5.9.2.tar.gz
md5=9687c14532a90af1098b646bde219a70
sha512=44ad793741a3ba52dfc07a190790d6e3207f146c42a4e1e11adc76f9d7fc9bee93d7fe18376882bb27e7e7e286be5807498884367b172a4ebc067028fa0c824c

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: 27 Aug 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"
  4. ocaml >= "4.08"
  5. dune >= "3.15"

Dev Dependencies (2)

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

Conflicts

None